python - 为什么 Sphinx/pythonhosted.org 中没有显示数学公式？

Question

我不确定问题到底出在哪里。

我开发了一个名为 hwrt 的 Python 包它在 pythonhosted.org(setuputils 自动放置它的官方站点)上托管它的文档。

我让 Sphinx 自动从文档字符串生成文档。一些模块文档字符串包含数学，例如来自 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."""

但是当我去 https://pythonhosted.org/hwrt/features.html#hwrt.features.ConstantPointCoordinates它不使用 mathjax 显示数学。为什么会这样？我该如何解决？

我的 Sphinx 的 conf.py 有

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

Answer 1

参见 Sphinx documentation on math support对于下面的句子:

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").

按照此建议，您必须将第一个数学句子更改为例如

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

---

更新

您的问题是您通过 https 访问 pythonhosted 但尝试通过 http 加载 mathjax 文件，这在默认情况下被阻止。在 Chrome 的控制台中查看错误消息

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.

尝试更改 https://pythonhosted.org/hwrt/features.html#hwrt.features.ConstantPointCoordinates至 http://pythonhosted.org/hwrt/features.html#hwrt.features.ConstantPointCoordinates一切都显示得很好。

解决方案是不硬编码，而是省略导入的 javascript 库的协议(protocol)。不要使用 http://cdn.mathjax.org/... 运行外部 javascript，而只使用 //cdn.mathjax.org/...

参见 this question on SO和 http://blog.jonathanoliver.com/http-and-https-with-google-cdn/了解更多详情

另一个可以准确解决您的问题的资源是 https://github.com/MDAnalysis/mdanalysis/issues/182