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

[Georg Brandl]

On 09/22/2013 12:16 PM, Nick Coghlan wrote:
> On 22 September 2013 18:54, Georg Brandl <g.brandl at gmx.net> wrote:
>> I don't really buy the argument "but then there is no complete documentation
>> set in the checkout" -- who reads that in preference to docs.python.org?
>> And if anybody does want plain-text docs, they are already available for build
>> and for download anyway (reST processed by Sphinx to remove non-plain markup).
> 
> This argument only applies to projects which have source and docs in
> separate checkouts, which doesn't apply to CPython :)
> 
> As others have noted, the preferred approach is indeed to maintain the
> prose docs independently of the docstrings. The latter are often
> trimmed to just be a quick reminder of the details of how the function
> works for those that already know, while the prose docs go into more
> depth and have more examples.

That is the convincing argument, yes.

It could be argued that autodoc allows adding content in the rst file itself,
such as

.. autofunction:: mean

   <docstring would go here in the output>

   Examples::

       >>> mean(life)
       "Try and be nice to people, avoid eating fat, read a good book ..."

But that means that when touching the docstring, one always has to look in
the rst file as well to check if the added content still makes sense.

cheers,
Georg