[Python-Dev] Best practice for documentation for std lib (original) (raw)

Georg Brandl g.brandl at gmx.net
Sun Sep 22 10:54:42 CEST 2013

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

More information about the Python-Dev mailing list