Martin Thoma - 1 year ago 63

Python Question

I am not sure where exactly the problem is.

I have developed a Python package called

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`

`extensions = [`

'sphinx.ext.autodoc',

'sphinx.ext.intersphinx',

'sphinx.ext.todo',

'sphinx.ext.coverage',

'sphinx.ext.mathjax'

]

Answer Source

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