> 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. > 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. Regards _______________________________________________ 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
