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
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
