<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Sep 22, 2013 at 6:06 AM, Georg Brandl <span dir="ltr"><<a href="mailto:g.brandl@gmx.net" target="_blank">g.brandl@gmx.net</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="im">On 09/22/2013 02:54 PM, Eli Bendersky wrote:<br>
><br>
><br>
><br>
> On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano <<a href="mailto:steve@pearwood.info">steve@pearwood.info</a><br>
</div><div class="im">> <mailto:<a href="mailto:steve@pearwood.info">steve@pearwood.info</a>>> wrote:<br>
><br>
>     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>
><br>
><br>
> IMHO the right way to think about it is that the .rst files are by far the more<br>
> important documentation. Sometimes we forget that most Python programmers are<br>
> people who won't go into the source to read docstrings. Moreover, the nice web<br>
> layout, table of contents, index, and link-ability of .rst is very important - I<br>
> also prefer to read it as opposed to going through docstrings.<br>
<br>
</div>Note -- using autodoc gives you this.<br>
<div class="im"><br>
> I only go to docstrings/code when I didn't find something in the .rst docs, at<br>
> this point also usually opening a bug to fix that.<br>
> So whatever you do for statistics, full .rst docs must be there.<br>
<br>
</div>I guess you don't mean .rst here; you mean .html (or .pdf, etc), whatever the<br>
toolchain outputs.<br></blockquote><div><br></div><div>Yes, by .rst docs I mean the final HTML output, not the .rst files themselves :-)<br><br></div><div> Paul Moore:<br>>While I agree entirely with this, it's worth noting that with the<br>


increasing popularity of IPython (even outside of the scientific<br>
community), more and more people are becoming used to using docstrings<br>
as a first means of finding out about a function's behaviour.</div></div>--<br><br></div><div class="gmail_extra">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:<br>

<br></div><div class="gmail_extra">1. Maintaining both, as tiresome as it is (we try to do this, not always successfully, for all stdlib modules).<br></div><div class="gmail_extra">2. autodoc<br><br></div><div class="gmail_extra">

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