On 22 September 2013 18:54, Georg Brandl
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@gmail.com | Brisbane, Australia