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

[Nick Coghlan]

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.

It's a bit of a pain, and we do occasionally get bug reports where the
docstrings get out of date, but it's the least bad of the currently
available options.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia