view raw
Martin Thoma - 9 months ago 40
Python Question

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

I am not sure where exactly the problem is.

I have developed a Python package called

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'
]


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