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

[Eli Bendersky]

On Sun, Sep 22, 2013 at 6:06 AM, Georg Brandl <g.brandl at gmx.net> wrote:

> On 09/22/2013 02:54 PM, Eli Bendersky wrote:
> >
> >
> >
> > On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano <steve at pearwood.info
> > <mailto:steve at pearwood.info>> wrote:
> >
> >     Hi all,
> >
> >     I have a question about how I should manage documentation for the
> >     statistics module for Python 3.4. At the moment, I have extensive
> >     docstrings in the module itself. I don't believe anyone has flagged
> that
> >     as "too much information" in a code review, so I'm going to assume
> that
> >     large docstrings will be acceptable.
> >
> >     However, I have been asked to ensure that there is a separate
> >     statistics.rst file for documentation.
> >
> >     I don't want to have to maintain the documentation in two places,
> both
> >     in the .py module and in .rst file. Can anyone give me some pointers
> as
> >     to best practice in this situation? Is there a "How To Write Docs For
> >     The Standard Library" document somewhere? Perhaps I missed it, but my
> >     searches found nothing useful. I have read this:
> >
> >     http://docs.python.org/devguide/documenting.html
> >
> >     but it didn't shed any light on my situation.
> >
> >
> > IMHO the right way to think about it is that the .rst files are by far
> the more
> > important documentation. Sometimes we forget that most Python
> programmers are
> > people who won't go into the source to read docstrings. Moreover, the
> nice web
> > layout, table of contents, index, and link-ability of .rst is very
> important - I
> > also prefer to read it as opposed to going through docstrings.
>
> Note -- using autodoc gives you this.
>
> > I only go to docstrings/code when I didn't find something in the .rst
> docs, at
> > this point also usually opening a bug to fix that.
> > So whatever you do for statistics, full .rst docs must be there.
>
> I guess you don't mean .rst here; you mean .html (or .pdf, etc), whatever
> the
> toolchain outputs.
>

Yes, by .rst docs I mean the final HTML output, not the .rst files
themselves :-)

 Paul Moore:
>While I agree entirely with this, it's worth noting that with the
increasing popularity of IPython (even outside of the scientific
community), more and more people are becoming used to using docstrings
as a first means of finding out about a function's behaviour.
--

That's a good point. I would still posit that HTML documentation gets by
far the most use, but docstrings are definitely important too. One more
point in favor of either:

1. Maintaining both, as tiresome as it is (we try to do this, not always
successfully, for all stdlib modules).
2. autodoc

Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130922/2791ac89/attachment.html>