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

[Dag Sverre Seljebotn]

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