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

[Westley Martínez]

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