[Python-Dev] Best practice for documentation for std lib (original) (raw)

Steven D'Aprano steve at pearwood.info
Sun Sep 22 05:13:04 CEST 2013

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

More information about the Python-Dev mailing list