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

Georg Brandl g.brandl at gmx.net
Wed Jul 7 20:27:32 CEST 2010

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

More information about the Python-Dev mailing list