<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano <span dir="ltr"><<a href="mailto:steve@pearwood.info" target="_blank">steve@pearwood.info</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi all,<br>
<br>
I have a question about how I should manage documentation for the<br>
statistics module for Python 3.4. At the moment, I have extensive<br>
docstrings in the module itself. I don't believe anyone has flagged that<br>
as "too much information" in a code review, so I'm going to assume that<br>
large docstrings will be acceptable.<br>
<br>
However, I have been asked to ensure that there is a separate<br>
statistics.rst file for documentation.<br>
<br>
I don't want to have to maintain the documentation in two places, both<br>
in the .py module and in .rst file. Can anyone give me some pointers as<br>
to best practice in this situation? Is there a "How To Write Docs For<br>
The Standard Library" document somewhere? Perhaps I missed it, but my<br>
searches found nothing useful. I have read this:<br>
<br>
<a href="http://docs.python.org/devguide/documenting.html" target="_blank">http://docs.python.org/devguide/documenting.html</a><br>
<br>
but it didn't shed any light on my situation.<br></blockquote></div><br></div><div class="gmail_extra">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. 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.<br>

<br>So whatever you do for statistics, full .rst docs must be there. It's the docstrings that are "optional" here. The best solution may be auto generating, for sure. But a module without .rst documented is unacceptable.<br>

<br></div><div class="gmail_extra">Eli<br></div><div class="gmail_extra"><br></div></div>