Why are math formulas not displayed in Sphinx / pythonhosted.org?

Question

I am not sure where exactly the problem is.

I have developed a Python package called hwrt which hosts its documentation on pythonhosted.org (the officiall site where setuputils automatically puts it).

I let Sphinx automatically generate the documentation from docstrings. Some modules docstrings contain math like the following docstring from features.py:

"""Take the first ``points_per_stroke=20`` points coordinates of the first
   ``strokes=4`` strokes as features. This leads to
   :math:`2 \cdot \text{points\_per\_stroke} \cdot \text{strokes}`
   features.
   If ``points`` is set to 0, the first ``points\_per\_stroke`` point
   coordinates and the \verb+pen_down+ feature is used. This leads to
   :math:`3 \cdot \text{points_per_stroke}` features."""

But when I go to https://pythonhosted.org/hwrt/features.html#hwrt.features.ConstantPointCoordinates it does not display the math with mathjax. Why is that the case and how can I fix it?

My conf.py for Sphinx has

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax'
]

Answer 1

See the Sphinx documentation on math support for the following sentence:

Keep in mind that when you put math markup in Python docstrings read by autodoc, you either have to double all backslashes, or use Python raw strings (r"raw").

Following this advice you have to change your first math sentence for example to

:math:`2 \\cdot \\text{points\\_per\\_stroke} \\cdot \\text{strokes}`

---

Update

Your problem is that you access pythonhosted over https but try to load the mathjax file over http, which is blocked by default. See the error message in Chrome's console

The page at 'https://pythonhosted.org/hwrt/features.html#hwrt.features.ConstantPointCoordinates' was loaded over HTTPS, but ran insecure content from 'http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML': this content should also be loaded over HTTPS.

Try changing https://pythonhosted.org/hwrt/features.html#hwrt.features.ConstantPointCoordinates to http://pythonhosted.org/hwrt/features.html#hwrt.features.ConstantPointCoordinates and everything is displayed just fine.

The solution is that you do not hardcode but omit the protocol for the imported javascript library. Instead of running the external javascript with http://cdn.mathjax.org/... use just //cdn.mathjax.org/...

See this question on SO and http://blog.jonathanoliver.com/http-and-https-with-google-cdn/ for more details

Another source to read that addresses exactly your problem is https://github.com/MDAnalysis/mdanalysis/issues/182