On 2013-09-22, at 21:24 , Westley Martínez wrote: >> From: gvanros...@gmail.com [mailto:gvanros...@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@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
