[docs] [issue28710] Sphinx incompatible markup in the standard library
Terry J. Reedy
report at bugs.python.org
Sun Jun 17 21:45:52 EDT 2018
Terry J. Reedy <tjreedy at udel.edu> added the comment:
In my last comment above, I forgot that this issue is about *docstrings*. We do not officially process docstrings with Sphinx, so there are no warnings to be suppressed.
PEP 8, which covers style for the stdlib, refers to https://www.python.org/dev/peps/pep-0257/
Neither says anything about markup and last I remember, there should not be any for the stdlib. Pep-0257 gives this example:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
Here, parameter names are indicated by the formatting, not by markup. If `' is used in such lists, it should just be deleted. I believe 'name' is sometimes used in running text.
The help() function prints a docstring as is.
Python tracker <report at bugs.python.org>
More information about the docs