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....@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: 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/anikom15%40gmail.com
_______________________________________________ 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
