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

[Xavier Morel]

On 2013-09-22, at 21:24 , Westley Martínez wrote:

>> From: gvanrossum at gmail.com [mailto:gvanrossum at gmail.com] On Behalf Of Guido
>> van Rossum
>> Sent: Sunday, September 22, 2013 11:35 AM
>> 
>> You seem to misunderstand the use of "autogeneration". It refers to generating
>> the .rst docs from the docstrings in the source. And FWIW, I'm against that
>> practice. 
> 
> Oh I see.  Well in that case, the docstrings can still become outdated,
> and so then the .rst docs will be outdated, too.

The points here are that there's a single source of truth (so we can't
have conflicting docstring and rst documentation), and documentation
becoming outdated can be noticed from both docstring and published
documentation.

>  It doesn't seem to
> offer much benefit since you still have to keep both updated, plus you
> have an extra tool that must be maintained.

There is no extra tool, autodoc is part of the standard Sphinx
distribution: http://sphinx-doc.org/ext/autodoc.html