MathJax for the Sphinx docs
Aaron Meurer
really easy. You just have to copy a file to the doc/src directory
and make a couple of changes to the conf.py file. I have done this at
my mathjax branch (https://github.com/asmeurer/sympy/tree/mathjax).
More information (also in the commit message):
See https://bitbucket.org/kevindunn/sphinx-extension-mathjax/wiki/Home
and
https://groups.google.com/forum/#!msg/sphinx-dev/SkLZlqapcM8/tI2qk5uTY3gJ.
MathJax renders the LaTeX equations in the browser. This has several
advantages:
- Compiling the Sphinx docs from scratch is *way* faster, since it
doesn't have to compile the LaTeX images. Previously on my machine, it
took about half an hour to compile from scratch (mainly due to heavy
LaTeX use in the mpmath docs). Now it only takes a couple of minutes.
- Because no LaTeX images are stored, the overall size of the compiled
docs is smaller.
- The rendered math in the browser is selectable (which also means it's
searchable), and crisp at arbitrary zoom levels, since it renders the
math using actual fonts, not images. So it's just like an equation in a
regular LaTeX pdf document.
- You can right click on the equation and get a menu that will show the
source. As a side benefit, you can also use this to convert the LaTeX
to mathml.
- No changes are required in the source files. This uses the same
:math: pragma as the previous system, so it's very swappable.
- This currently uses an online version of the mathjax.js file that is
free to use for production, but this can easily be downloaded and used
locally for offline use.
Disadvantages:
- You will not be warned about LaTeX errors at doc compile time. The
only way I know to find them is to look at all the rendered html files
for yellow MathJax error boxes. Perhaps there is a more streamlined way
to do this, though.
- There currently are some errors in the GA docs, due to some strange
control sequences like \W and \lbrk. I'm not sure where these are
defined, but this will have to be fixed if we use this.
- Your browser has to render the math at load time, which makes it a
little slower for LaTeX intensive pages. Actually, it isn't too bad.
And it seems to render from the top down, so you can see the math at the
top almost immediately. And while it is rendering, you see the LaTeX
source, so you can at least read it.
To compare this against the old system checkout my branch and, do
cd doc
make clean # To clear the old docs
make html
And open a LaTeX intensive page like
_build/html/modules/mpmath/functions/hypergeometric.html in your browser
and compare it against the current page at docs.sympy.org (in this case,
http://docs.sympy.org/0.7.0/modules/mpmath/functions/hypergeometric.html#mpmath.hyp0f1).
Note how with the MathJax, you can select parts of the math equations,
you can zoom in (using your browser's zoom functionality) without any
loss of resolution, and you right click on the equation to get the
source.
Aaron Meurer
Aaron Meurer
it looks like by pushing a demo up to docs.sympy.org.
Go to http://docs.sympy.org/mathjax/ and navigate to a LaTeX intensive
page (the mpmath function pages are good examples). Then compare
against the same page replacing "mathjax" in the url with "dev".
You can see on some pages there are errors (yellow boxes). For
example, at http://docs.sympy.org/mathjax/modules/galgebra/GA/GAsympy.html.
This is because they are somehow defining custom control sequences.
I haven't figured out how to make these work with MathJax yet. I want
to see if people like this idea before I try anything further.
By the way, the built mathjax docs are 7.3 MB, whereas the built docs
using the current method are 13 MB.
Aaron Meurer
Aaron Meurer
while to render the math, due to the slower processor, but once it
does, it's worth it, because it's way crisper when you zoom in, which
you tend to do a lot on these mobile devices with their small screens.
And anyway, like I said, you can at least see the LaTeX math while
you're waiting for it to render, which is readable.
Aaron Meurer
Brian Granger
great, so I think this would be a good move.
Is there anyway of getting latex output in the sympy code samples?
Cheers,
Brian
> --
> You received this message because you are subscribed to the Google Groups "sympy" group.
> To post to this group, send email to sy...@googlegroups.com.
> To unsubscribe from this group, send email to sympy+un...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/sympy?hl=en.
>
>
--
Brian E. Granger
Cal Poly State University, San Luis Obispo
bgra...@calpoly.edu and elli...@gmail.com
Aaron Meurer
built to combine rendered math and doctests. If you add something
like
>>> something
`\pi`
or
>>> something
:math:`\pi`
in a doctest, it will just render it as
>>> something
\(\pi\)
So it doesn't seem like it would be as easy as redefining the
displayhook. Perhaps Sphinx could be modified to do this? We would
have to ask on their list. Maybe the solution would have to be to
write our own custom Sphinx extension that reders LaTeX math in
doctests, and then just setting the displayhook to a modified latex
function that puts backtiks around the equations.
By the way, I just noticed that if you have a search term highlighted,
it highlights the latex without rendering it, like
http://docs.sympy.org/mathjax/modules/mpmath/functions/constants.html?highlight=pi#mpmath.mp.pi.
I'm not sure if that's a good thing or not.
Aaron Meurer
Aaron Meurer
errors. In conf.py there is a pngmath_latex_preamble, which defines a
bunch of \newcommands that are recognized by pngmath and math_dollar,
but not mathjax. There isn't anything in the mathjax sphinx extension
docs or the mathjax.py file that would lead me to believe that a
similar feature is allowed for mathjax, but I could be wrong.
Otherwise, we will just have to add the \newcommands to the top of the
relevant files, which works (this is clearer anyway, imho).
So now the only question is, is there a streamlined way to find
MathJax errors throughout the docs?
Aaron Meurer
Vinzent Steinberg
> I figured out why some documents give "Undefined control sequence"
> errors. In conf.py there is a pngmath_latex_preamble, which defines a
> bunch of \newcommands that are recognized by pngmath and math_dollar,
> but not mathjax. There isn't anything in the mathjax sphinx extension
> docs or the mathjax.py file that would lead me to believe that a
> similar feature is allowed for mathjax, but I could be wrong.
>
> Otherwise, we will just have to add the \newcommands to the top of the
> relevant files, which works (this is clearer anyway, imho).
>
> So now the only question is, is there a streamlined way to find
> MathJax errors throughout the docs?
Vinzent
Aaron Meurer
Which version are you using? According to
http://www.mathjax.org/resources/browser-compatibility/, it should
work with IE6 and up.
Aaron Meurer
Aaron Meurer
docs for compilation errors. I'll let you know what they reply.
Aaron Meurer
Ondrej Certik
> I've made this easer for people who just want to play around with what
> it looks like by pushing a demo up to docs.sympy.org.
>
> Go to http://docs.sympy.org/mathjax/ and navigate to a LaTeX intensive
> page (the mpmath function pages are good examples). Then compare
> against the same page replacing "mathjax" in the url with "dev".
>
> You can see on some pages there are errors (yellow boxes). For
> example, at http://docs.sympy.org/mathjax/modules/galgebra/GA/GAsympy.html.
> This is because they are somehow defining custom control sequences.
> I haven't figured out how to make these work with MathJax yet. I want
> to see if people like this idea before I try anything further.
>
> By the way, the built mathjax docs are 7.3 MB, whereas the built docs
> using the current method are 13 MB.
For my book, where I use *tons* of math in sphinx:
http://theoretical-physics.net/
I also tried mathjax, but some of the pages take forever to load. So I
decided to stick with latex, which is not ideal, but is very robust
and renders fast.
SymPy docs don't contain nearly as much math as
theoretical-physics.net, so I think we can try to use mathjax, and if
it turns out that the experience is worse, we can always revert it
back to latex. So I would give it a shot.
Ondrej
Aaron Meurer
Some of the pages do. I've tested it with some of the pages from Tom's
gsoc branch which contain a lot of math, and it has worked fine. The
benefit is that the build time is *way* faster, and you also save a
ton of disk space by not having LaTeX images (even our docs were half
the size, and that's just with math mainly in the mpmath docs).
And of course, the MathJax math looks way nicer.
Aaron Meurer
Aaron Meurer
If someone here could review the branch, that would be great, so I can
start the release cycle (I want this to be in the release, and I would
like to get a release candidate out tomorrow).
Aaron Meurer