On 22 September 2013 18:54, Georg Brandl <g.bra...@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 | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
