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

[Georg Brandl]

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.

cheers,
Georg