[Python-Dev] query: docstring formatting in python distutils code (original) (raw)

Robert Kern robert.kern at gmail.com
Wed Jul 7 20:26:50 CEST 2010

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

More information about the Python-Dev mailing list