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

Nick Coghlan ncoghlan at gmail.com
Sun Sep 22 12:16:00 CEST 2013

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

More information about the Python-Dev mailing list