[Python-Dev] query: docstring formatting in python distutils code

[Terry Reedy]

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