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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com