Nick Coghlan added the comment: As far as using docstrings for the online docs goes, there are some useful Sphinx add-ons that we've never enabled for the main Python docs (like autodoc, blockdiag, seqdiag) that could be good options to have available. For autodoc in particular, we prefer to avoid it for the main docs because "good docstring" and "good prose documentation" don't necessarily look alike. For ease of maintenance of test.support though, I think the "write a good docstring, get the online docs for free" rationale is a compelling one (since these docs are core contributor facing, rather than being aimed at Python users in general)
d...@python.org would be the place to ask about the appropriateness of enabling some Sphinx add-ons. While enabling them seems like a reasonable idea to me, I don't personally know if there are actually technical issues with the idea, or if there just hasn't been a volunteer to add/enable them and update https://docs.python.org/devguide/documenting.html accordingly. ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue18576> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
