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

[Georg Brandl]

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

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.

>> Agreed.  However, reST doesn't need to be less readable if the specific
>> inline markup is not used.  For example, using `identifier` to refer to a
>> function or *var* to refer to a variable (which is already done at quite a
>> few places) is very readable IMO.  Using ``code`` also isn't bad, considering
>> that double quotes are not much different and potentially ambiguous.
>> 
>> Overall, I think that we can make stdlib docstrings valid reST -- even if it's
>> reST without much markup -- but valid, so that people pulling in stdlib doc-
>> strings into Sphinx docs won't get ugly warnings.
>> 
>> What I would *not* like to see is heavy markup and Sphinx specifics -- that
>> would only make sense if we included the docstrings in the docs, and I don't
>> see that coming.
> 
> Clear answer, thanks! We have backported some modules in distutils2, and
> some docstrings already contain Sphinxy reST (e.g. :param: and :pep:),
> it’s good to know now that we shouldn’t put hours into that to see it
> reverted later.

:pep: isn't Sphinxy, put provided by docutils, and the :param foo: field
lists are also valid reST, if rendered a bit awkwardly without the transforms
that Sphinx does to display them in epydoc style.

cheers,
Georg