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

[Robert Kern]

On 7/7/10 1:53 PM, Éric Araujo wrote:
>> I promised to write a PEP about that some time in the future.  (Probably after
>> 3.2 final.)
>
> Nice.
>
> 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.

This is a false dichotomy. Many of those projects using Sphinxy reST in their 
docstrings are using the semi-automatic[1] doc generation provided by Sphinx to 
construct *part* of their documentation. Namely, the reference of functions, 
classes and methods. A large part of Python's library reference consists of 
exactly this. Having a function's docstring provide the content for its entry in 
the library reference has the substantial DRY benefit of having exactly one 
source for the comprehensive documentation of that function available from both 
help() and the manual. As someone who uses the interactive prompt to play with 
things and read docstrings intensively, I would really like to see docstrings 
providing the same information as the manual.

Of course, opinions differ about how comprehensive docstrings should be compared 
to the reference manual's entries. And there are technical reasons for not 
wanting to try to extract docstrings from code (e.g. platform-specific modules). 
But one should not fear that the quality of the manual would decline.

[1] That's the really nice thing about Sphinx's docstring extraction features in 
contrast with other such tools. It doesn't generate a manual from the 
docstrings; it makes you explicitly reference the docstrings into the manual's 
text. This would fit in very naturally with Python's library reference.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
  that is made terrible by our own mad attempt to interpret it as though it had
  an underlying truth."
   -- Umberto Eco