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

Serhiy Storchaka report at bugs.python.org
Mon Jun 18 12:30:00 EDT 2018

Serhiy Storchaka <storchaka+cpython at gmail.com> added the comment:

What is the problem? Docstrings are not written in the reStructuredText format in general. If Sphinx complains about docstrings in the stlib, don't run Sphinx for the stdlib files or report a Sphinx bug. Even if remove all `x', docstrings still will not be valid reStructuredText. For example the last three lines will be joined in a single paragraph for the docstring in msg319848.

`name' does not have special meaning in (La)TeX. AFAIK `name' is common writing of quotes in English texts. It predates reStructuredText and was widely used in Usenet and mailing lists (as two spaces after sentence-ending punctuation, double hyphen for a dash, _n_a_m_e_ to simulate underscoring, etc). It is just a part of old computer-typing culture (or may be even pre-computer).

nosy: +serhiy.storchaka

Python tracker <report at bugs.python.org>

More information about the docs mailing list