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

[Steven D'Aprano]

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.


Thanks in advance,



-- 
Steve