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

[Georg Brandl]

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