由于 HTML-CSS 渲染器，使用 Sphinx 渲染 MathJax 的问题答案

【问题标题】：Issues rendering MathJax using Sphinx due to HTML-CSS renderer由于 HTML-CSS 渲染器，使用 Sphinx 渲染 MathJax 的问题
【发布时间】：2019-03-25 16:52:17
【问题描述】：

我刚刚升级到以下：

Sphinx==1.8.5
nbconvert==5.4.1
pandoc==1.0.2

我一直能够使用 Sphinx 通过 jupyter 笔记本在文档中呈现数学（seaborn 的方式）。但是，升级后，数学不再渲染！如果我右键单击方程式应该在的位置，我可以将数学渲染器更改为“svg”或“CommonHTML”，一切都很好 - 无论出于何种原因，它都不会使用默认的“HTML-CSS”数学渲染器进行渲染。我的问题是：如何更改配置文件中的默认渲染器？

我尝试了什么：

conf.py

...
extensions = [
    ...
    'sphinx.ext.mathjax'
    ...
]
...

mathjax_config = {
    'jax': ['input/TeX', 'output/CommonHTML']
}

然而，这并没有像我想象的那样改变默认渲染器。有谁知道如何在 Sphinx 中更改 MathJax 的默认渲染器？

这是一个 gif：

此外，MathJax 似乎是从 CDN 加载的首选配置：

【问题讨论】：

MathJax 上下文菜单中的设置会覆盖文件中的设置，因此如果您使用菜单尝试不同的渲染器，那么这些设置可能仍然有效。尝试删除本地文件的 cookie（因为您使用的是file:// URL）。如果不是这样，请检查 MathJax.js 是否正在加载 ?config= 参数，因为它们会加载特定的输入和输出渲染器，并且您的 jax 配置将不会被使用。其中任何一个都可能是问题所在。
嗯，它们似乎正在加载配置参数（上面添加的图像）。强制MathJax 使用 sphinx-config 中的参数的最简单方法是什么？

标签： python python-sphinx mathjax autodoc

【解决方案1】：

我不确定MathJax 之前是如何为您工作的，但基于Sphinx-documentation MathJax 默认情况下不包含在Sphinx 中。您必须在 conf.py 中指定 mathjax_path，例如使用本地版本或托管在 cdnjs 中的服务器。

【讨论】：

嗯..它看起来确实像 MathJax 被默认包含在 CDN 中 - 它显示在 chrome 开发人员的网络选项卡中 - 它最初似乎加载良好，然后隐藏了所有无论出于何种原因数学......
我明白了，这个问题是否只发生在 Chrome 或其他浏览器上？我在使用 Sphinx 时遇到了类似的问题，但它只出现在 Firefox 上。
好问题 - Safari 似乎无法在我的 MBP 上运行，但这里有一个链接：dhhagan.github.io/opcsim/tutorial/distribution.html

【解决方案2】：

虽然我无法使用 mathjax_config 方法，但我仍然可以通过使用 CommonHTML 的 CDN 将 mathjax_path 设置为特定的输出处理器。

因此，一个可行的答案是编辑conf.py 文件以包含一行：

...
mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML"
...

【讨论】：

这与我的答案几乎相同，我的编辑就足够了。