Author ncoghlan
Recipients Fotis.Koutoulakis, bobcatfish, docs@python, eric.snow, ezio.melotti, martin.panter, ncoghlan, serhiy.storchaka, seydou
Date 2015-06-07.05:45:02
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1433655902.86.0.349167589574.issue18576@psf.upfronthosting.co.za>
In-reply-to
Content
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)

docs@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.
History
Date User Action Args
2015-06-07 05:45:02ncoghlansetrecipients: + ncoghlan, ezio.melotti, docs@python, eric.snow, martin.panter, serhiy.storchaka, seydou, Fotis.Koutoulakis, bobcatfish
2015-06-07 05:45:02ncoghlansetmessageid: <1433655902.86.0.349167589574.issue18576@psf.upfronthosting.co.za>
2015-06-07 05:45:02ncoghlanlinkissue18576 messages
2015-06-07 05:45:02ncoghlancreate