[Python-Dev] Best practice for documentation for std lib

[Georg Brandl]

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