On 7/7/2010 2:27 PM, Georg Brandl wrote: > Am 07.07.2010 19:53, schrieb Éric Araujo: >>> I promised to write a PEP about that some time in the future. (Probably after >>> 3.2 final.) >> It seems that projects putting Sphinxy reST in their doc are using >> automatic doc generation. This is however not always the best way to >> make good doc, as demonstrated by Python’s hand-written, >> very-high-quality documentation. > I know, and this is what I originally intended for Sphinx. However, the calls > for automatic doc generation are very loud, and it's understandable that most > project can't afford writing their documentation twice. Neither can CPython, really, as evidenced by numerous examples that have shone up on the tracker. Let me add another one. A week ago, Eli Benderdky asked me for help adding missing pieces to the trace module doc. The result so far is http://bugs.python.org/issue9264 After getting that far, I noticed that there were already doc strings for some things that were not documented in the manual, which we added. I also noticed the the public methods already in the manual had not help strings, and hence no helpful help() output. In other words, the manual entries and doc strings were close to disjoint sets. Even when they do overlap as they should, violation of DRY is a maintenance nightmare when anything changes. It would be better if the manual could, to some extent, be docstrings plus additions. -- Terry Jan Reedy
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