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

Dag Sverre Seljebotn d.s.seljebotn at astro.uio.no
Mon Sep 23 17:17:31 CEST 2013

On 09/23/2013 04:43 PM, R. David Murray wrote:

On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum <guido at python.org> wrote:

On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel <python-dev at masklinn.net>wrote:

The points here are that there's a single source of truth (so we can't have conflicting docstring and rst documentation), and documentation becoming outdated can be noticed from both docstring and published documentation. Another thing that hasn't been mentioned about docstrings vs rst docs, is that even when the text is identical, it generally isn't. By that I mean the rst docs have ReST markup, but the docstrings don't. So using

FYI, the scientific Python community have their own standard (the NumPy docstring standard), with light RST markup in docstrings:

https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

It's a fairly popular standard in the scientific sub-culture.

I think there's something about scientific codes which tips the scales away from Guido's position of short docstrings being better; when working with computation, you pretty much need the documentation, formulas, references to paper it is based on and so on in order to read and understand the code in the first place, so interspersing makes more sense than it may in the stdlib. Seeing code with references "x", "alpha", "beta", "gamma" without their definition is pretty useless :-)

Dag Sverre

More information about the Python-Dev mailing list