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

[Georg Brandl]

Am 16.07.2010 22:55, schrieb 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.

And that's a pity -- very commendable that you work on this.  But this is
a single case, and most of our library is very well covered by the docs
and docstrings.  Additions (which usually are small amendments) are made
only in the docs, not the docstring, as it should be given the nature of
our docstrings.  Added functionality is usually documented first in
docstrings, which then get copied into the docs, and are padded from there.

> 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.

That sounds nice in theory, but opens another can of worms: what belongs
in the docstring, what in the "addition"?  How does it work for builtin
types, for language features, and so on.  Also, the problems I already
outlined in my answer to Fred remain...

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.