[Python-Dev] Best practice for documentation for std lib (original) (raw)

Xavier Morel python-dev at masklinn.net
Sun Sep 22 23:41:39 CEST 2013

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

More information about the Python-Dev mailing list