[docs] [issue28710] Sphinx incompatible markup in the standard library docstrings

Terry J. Reedy report at bugs.python.org
Mon Jun 18 15:37:03 EDT 2018

Terry J. Reedy <tjreedy at udel.edu> added the comment:

RestructuredText, DocUtils, and Sphinx were developed independently, by people other than the pydev/cpython group.  (The proposal to include DocUtils in the stdlib was rejected.)  We converted to .rst for the Python documentation sources files about a decade ago.  Sphinx turns them into the .html files you can see online.  RestructuredText markup can now also be used in PEP, news/changelog, and What's New sources.  These are things that most people only view online or in other processed forms, not in source form.

On the other hand, stdlib docstrings are mostly viewed unprocessed in .py sources or as output from help() in text consoles or text widgets.  So markup in stdlib docstrings would impact everyone, not just core developers.


Python tracker <report at bugs.python.org>

More information about the docs mailing list