[Python-Dev] Allow use of sphinx-autodoc in the standard library documentation? (original) (raw)

Georg Brandl g.brandl at gmx.net
Thu May 10 16:50:31 CEST 2012

On 10.05.2012 07:02, Nick Coghlan wrote:

One of the requirements for acceptance of PEP 3144 if the provision of a reStructuredText API reference.

The current plan for dealing with that is to use Spinx apidoc to create a skeleton, and then capture the rewritten ReST produced by autodoc. However, it occurs to me that the module reference could actually use autodoc, with additional prose added to supplement the docstrings, rather than completely replacing them. I'd initially dismissed this idea out of hand, but recently realised I didn't have any especially strong arguments against it (and there are all the usual "avoid double-keying data" arguments in favour). So, given the advantages of autodoc, is there a concrete reason why we can't use it for the documentation of new standard library modules?

The one reason that prevented me from ever proposing this is that to do this, you have to build the docs with exactly the Python you want the documentation for. This can create unpleasant dependencies for e.g. distributions, and also for developers who cannot build the docs without first building Python, which can be a hassle, especially under Windows. But of course we want people to build the docs before committing...

The other issue is the extensiveness of the docstrings vs. separate docs. So far, the latter have always been more comprehensive than the docstrings, which works nicely for me (although crucial info is sometimes missing in the docstring).

This difference can be kept, to a degree, even with autodoc, by putting additional content into the autodoc directive, but that renders one big autodoc advantage moot: having the documentation in one place only. Even worse, if someone changes the docstring, the addendum in the rst file may become wrong/obsolete/incomprehensible.

cheers, Georg

More information about the Python-Dev mailing list