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

Westley Martínez anikom15 at gmail.com
Sun Sep 22 23:49:56 CEST 2013

Well, I'm wholly confused now, so I'll leave this discussion to the devs.

-----Original Message----- From: Python-Dev [mailto:python-dev-bounces+anikom15=gmail.com at python.org] On Behalf Of Xavier Morel Sent: Sunday, September 22, 2013 2:42 PM To: python-dev Subject: Re: [Python-Dev] Best practice for documentation for std lib

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

Python-Dev mailing list Python-Dev at python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python- dev/anikom15%40gmail.com

More information about the Python-Dev mailing list