Hi,
I just ran across a behavior that took me a while to understand, so I
thought I would post it here.
Using autodoc and inline math to document a Python function, I had
unexpected errors in Sphinx. Here are the function and the error I got
while building it.
def ExtractSignals(paths, phases, data):
'''
Observable coherence pathways will always end with :math:`p=-1`.
However, extracting
other, virtual, pathways can be advantageous for diagnostics. As
an
example, a path of :math:`p=0 \rightarrow 0 \rightarrow \ldots
\rightarrow 0` will
yield the coherent noise background that does not depend on the
phase of the
(documentation continues)
'''
PhaseCycling.py:docstring of PhaseCycling.ExtractSignals:10: (WARNING/
2) Inline interpreted text or phrase reference start-string without
end-string.
PhaseCycling.py:docstring of PhaseCycling.ExtractSignals:12: (WARNING/
2) Block quote ends without a blank line; unexpected unindent.
This documentation compiles correctly in an rst file but does not work
when pulled into the rst file by autodoc.
The problem is that \r is a carriage return in Python strings, even in
triple-quoted strings. Python interprets most backslashes as just
backslashes, but \r, \n, \a, \b, \t, \f, \', \" and a few others are
read as control characters. For instance, in Python "\w" is two
characters, but "\n" is just one. Using "\\w" also leads to two
characters, as does "\\n", so the safest bet is to add an extra
backslash when writing math in Python docstrings for autodoc.
def ExtractSignals(paths, phases, data):
'''
Observable coherence pathways will always end with :math:`p=-1`.
However, extracting
other, virtual, pathways can be advantageous for diagnostics. As
an
example, a path of :math:`p=0 \\rightarrow 0 \\rightarrow \\ldots \
\rightarrow 0` will
yield the coherent noise background that does not depend on the
phase of the
(documentation continues)
'''
Hope This Helps Somebody,
Drew
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
