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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4