On 09/22/2013 05:13 AM, Steven D'Aprano wrote: > Hi all, > > I have a question about how I should manage documentation for the > statistics module for Python 3.4. At the moment, I have extensive > docstrings in the module itself. I don't believe anyone has flagged that > as "too much information" in a code review, so I'm going to assume that > large docstrings will be acceptable. > > However, I have been asked to ensure that there is a separate > statistics.rst file for documentation. > > I don't want to have to maintain the documentation in two places, both > in the .py module and in .rst file. Can anyone give me some pointers as > to best practice in this situation? Is there a "How To Write Docs For > The Standard Library" document somewhere? Perhaps I missed it, but my > searches found nothing useful. I have read this: > > http://docs.python.org/devguide/documenting.html > > but it didn't shed any light on my situation.
This is the "How To Write etc." document. If your docstrings really are complete, and marked up correctly, the new module *could* be the first to use Sphinx autodoc for the stdlib documentation. However, some core devs (including me) have stated opposition in the past. The reason I myself have never really wanted to do this for the stdlib, apart from most modules needing complete rewrites of their docstrings, is that when documenting a standard module, you have to go through a few hoops to make sure the build process actually imports the correct module to document, and not the one of the Python version used to build the docs (which can be different). I don't really buy the argument "but then there is no complete documentation set in the checkout" -- who reads that in preference to docs.python.org? And if anybody does want plain-text docs, they are already available for build and for download anyway (reST processed by Sphinx to remove non-plain markup). cheers, Georg _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
