[Python-Dev] Best practice for documentation for std lib
g.brandl at gmx.net
Sun Sep 22 15:06:40 CEST 2013
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:
> 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
More information about the Python-Dev