[Python-Dev] Best practice for documentation for std lib
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:
> 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
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).
More information about the Python-Dev