Hi guys,
I'm trying to use sphinx and your mathmpl extension to document some
of my own code, but I'm getting an error saying, in the simplest
instance:
Warning: Could not render math expression $alpha$
Is mathmpl dependent on a particular version of sphinx? I'm using
0.4.2-1 from debian at the moment. If that's not the problem, any idea
what else could be going wrong?
Thanks,
Angus.
--
AJC McMorland
Post-doctoral research fellow
Neurobiology, University of Pittsburgh
You don't need the $. In fact, an unescaped $ in a math expression is a syntax error.
Admittedly, the feedback about this could be better than just "couldn't render". I'll look at passing more information about the exception back to Sphinx.
Note also, you'll want a slash in front of \alpha in order to get Greek, rather than "alpha".
Mike
Angus McMorland wrote:
Hi guys,
I'm trying to use sphinx and your mathmpl extension to document some
of my own code, but I'm getting an error saying, in the simplest
instance:Warning: Could not render math expression $alpha$
Is mathmpl dependent on a particular version of sphinx? I'm using
0.4.2-1 from debian at the moment. If that's not the problem, any idea
what else could be going wrong?Thanks,
Angus.
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA
Hi Mike et al,
Thanks for the reply.
2008/12/15 Michael Droettboom <mdroe@...86...>:
You don't need the $. In fact, an unescaped $ in a math expression is a
syntax error.Admittedly, the feedback about this could be better than just "couldn't
render". I'll look at passing more information about the exception back to
Sphinx.Note also, you'll want a slash in front of \alpha in order to get Greek,
rather than "alpha".
I think I've copied the usage suggested by the 'writing mathtext' page
in the mpl documentation (i.e. looking at its rst source [1]). That is
to say, the appearance of $ and the lack of \ are produced by the
extension, and not by me.
With this docstring:
"""
Test docstring with :math:`\alpha`
and longer
.. math::
\alpha = 2
"""
I get this error:
writing output... index modules/calculate
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha$
Warning)
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha = 2$
Warning)
I've just redownloaded the sphinx extensions from matplotlib svn, so
they're definitely all the latest versions.
Thanks for any pointers.
Angus.
--
AJC McMorland
Post-doctoral research fellow
Neurobiology, University of Pittsburgh
Angus McMorland wrote:
Hi Mike et al,
Thanks for the reply.
2008/12/15 Michael Droettboom <mdroe@...86...>:
You don't need the $. In fact, an unescaped $ in a math expression is a
syntax error.Admittedly, the feedback about this could be better than just "couldn't
render". I'll look at passing more information about the exception back to
Sphinx.Note also, you'll want a slash in front of \alpha in order to get Greek,
rather than "alpha".
I think I've copied the usage suggested by the 'writing mathtext' page
in the mpl documentation (i.e. looking at its rst source [1]). That is
to say, the appearance of $ and the lack of \ are produced by the
extension, and not by me.
I see what you're saying now. Sorry for the assumption.
With this docstring:
"""
Test docstring with :math:`\alpha`and longer
.. math::
\alpha = 2
"""
You'll need to use raw strings (prefix the """ with an r) so that the \a will appear in the final string.
I get this error:
writing output... index modules/calculate
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha$
Warning)
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha = 2$
Warning)I've just redownloaded the sphinx extensions from matplotlib svn, so
they're definitely all the latest versions.
That doesn't seem to be the root of this problem, however, as these strings should at least render to *something*, though probably not what you want.
The warning is hiding the real error here. In mathmpl.py, after the line where the warning is emitted:
warnings.warn("Could not render math expression %s" % latex,
Warning)
Add the line:
raise
and then post the output to this list?
Thanks,
Mike
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA
Hi Mike,
2008/12/15 Michael Droettboom <mdroe@...86...>:
Angus McMorland wrote:
I think I've copied the usage suggested by the 'writing mathtext' page
in the mpl documentation (i.e. looking at its rst source [1]). That is
to say, the appearance of $ and the lack of \ are produced by the
extension, and not by me.I see what you're saying now. Sorry for the assumption.
No problems. Thank-you for developing these great tools.
<snip>
You'll need to use raw strings (prefix the """ with an r) so that the \a
will appear in the final string.
I get this error:
writing output... index modules/calculate
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha$
Warning)
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha = 2$
Warning)
Excellent - the use of raw docstrings _does_ fix the errors during the
sphinx build.
That doesn't seem to be the root of this problem, however, as these strings
should at least render to *something*, though probably not what you want.The warning is hiding the real error here. In mathmpl.py, after the line
where the warning is emitted:warnings.warn("Could not render math expression %s" % latex,
Warning)Add the line:
raise
and then post the output to this list?
Just an FYI so you can probably tell what was going on, without the
curative r'', and with raise in place, the error reported was:
writing output... index modules/calculate
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha$
Warning)
Exception occurred:
File "/usr/lib/python2.5/site-packages/matplotlib/mathtext.py", line
1963, in raise_error
raise ParseFatalException(msg + "\n" + s)
ParseFatalException: Expected end of math '$'
$lpha$ (at char 0), (line:1, col:1)
Next, I initially got no pictures (a silent fail) in my browser, but I
traced that back to an assumption that mathmpl makes that sphinx-build
is being run from the html directory, whereas I was running it from
one higher up the hierarchy (my docs directory). Running sphinx-build
from the appropriate location makes it all work.
Obviously this is fine for mpl's needs (and mine too, now I know the
tricks). If, however, you're interested in making this a little more
robust for general usage, then the path handling probably needs
tweaking. I think the problem is that mathmpl.latex2html puts the
_static directory in the current directory sphinx-build is run from,
whereas in the html it points to '../_static/', which is not the same
thing whenever html pages are being rendered at deeper directory
levels.
Thanks,
Mike
Thanks for the help,
Angus.
--
AJC McMorland
Post-doctoral research fellow
Neurobiology, University of Pittsburgh
Angus McMorland wrote:
I get this error:
writing output... index modules/calculate
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha$
Warning)
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha = 2$
Warning)
Excellent - the use of raw docstrings _does_ fix the errors during the
sphinx build.That doesn't seem to be the root of this problem, however, as these strings
should at least render to *something*, though probably not what you want.The warning is hiding the real error here. In mathmpl.py, after the line
where the warning is emitted:warnings.warn("Could not render math expression %s" % latex,
Warning)Add the line:
raise
and then post the output to this list?
Just an FYI so you can probably tell what was going on, without the
curative r'', and with raise in place, the error reported was:writing output... index modules/calculate
/usr/lib/python2.5/site-packages/sphinx/ext/sphinxext/mathmpl.py:107:
Warning: Could not render math expression $lpha$
Warning)
Exception occurred:
File "/usr/lib/python2.5/site-packages/matplotlib/mathtext.py", line
1963, in raise_error
raise ParseFatalException(msg + "\n" + s)
ParseFatalException: Expected end of math '$'
$lpha$ (at char 0), (line:1, col:1)
Thanks -- that's a good clue, though I'm still not sure why it's failing. Glad to see you have it working for the time being anyway.
Next, I initially got no pictures (a silent fail) in my browser, but I
traced that back to an assumption that mathmpl makes that sphinx-build
is being run from the html directory, whereas I was running it from
one higher up the hierarchy (my docs directory). Running sphinx-build
from the appropriate location makes it all work.Obviously this is fine for mpl's needs (and mine too, now I know the
tricks). If, however, you're interested in making this a little more
robust for general usage, then the path handling probably needs
tweaking. I think the problem is that mathmpl.latex2html puts the
_static directory in the current directory sphinx-build is run from,
whereas in the html it points to '../_static/', which is not the same
thing whenever html pages are being rendered at deeper directory
levels.
For clarification, the matplotlib doc build creates the images within the doc/ directory and then copies them to the build. But that's not ideal either -- I agree the "file handling" stuff needs to be improved.
Long term, I think I'll need to look at what the new(ish) math extensions in the sphinx core do and emulate that. Just haven't found the time to get around to it lately.
Cheers,
Mike
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA