On 09/22/2013 02:54 PM, Eli Bendersky wrote: > > > > On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano <st...@pearwood.info > <mailto:st...@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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
