如何让Sphinx_doc支持MathJax公式
作者：互联网
参考资料：
https://github.com/mathjax/MathJax/
https://gitlab.com/thomaswucher/sphinx-mathjax-offline/-/tree/master/
如果你点进这篇文章，那么你的目的一定是想让自己的以Sphinx_doc为基础搭建的在线文档支持MathJax。
实现这个目的难吗？一点都不难，但是sphinx是以扩展的形式来支持MathJax数学公式渲染的，并且坦白地说，它支持的一点都不好。下面是我自己摸索的操作步骤，花了不少时间，因为中英文网站上关于sphinx doc支持MathJax的tutorial基本没有。
必须知道的事情，sphinx doc支持MathJax本质上就是在web页面里面嵌入一个javascript程序，这个程序由浏览器下载到本地，再在本地运行以渲染出美轮美奂的数学公式。那么，这个js程序的来源有两个：1. 公网上下载 2. 直接放在服务器上供浏览器下载。两种办法都完全可以啊，但是使用第一种的话必须要求你的电脑可以访问互联网，但是使用第二种，只需要你的电脑可以访问host在线文档的服务器即可。
1. 直接配置插件即可
按照参考资料2的文档中的做法，我们必须在sphinx doc目录下的conf.py文件中的extensions列表里加上一个字符串：‘sphinx.ext.mathjax’
extensions = [
'sphinx.ext.mathjax'
]
加上这个字符串之后，使用make html重新编译web页面，有一定的概率你的网站已经正确地把LaTeX公式渲染出来了。
为什么说一定概率，是因为后面我们会接触一个配置项mathjax_path，如果你根本不在conf.py里面加上这个配置变量，那么sphinx应当会直接从公网上下载我们需要的MathJax.js文件。如下图所示，这是用浏览器F12检视的结果，可以看到你的浏览器在渲染公式之前会从cdn网站下载所需的js。
如果你想显式地指定这个js程序从公网上下载下来，那么sphinx文档也给出了方法，在conf.py中指定这个地址即可。
mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
2. 使用辅助插件
第一种配置方法的最大好处就是省事，但是如果你的网不好，所需js下的慢，一个很明显的现象就是web页面的文字加载出来之后好一会儿数学公式才渲染出来。此时我们的想法是把所需js直接放在host在线文档的server上。一个插件可以满足功能：sphinx-mathjax-offline，按照参考资料3的README配置即可。
3. 适用于有强迫症的人
前两种办法已经非常省事了，但是我有强迫症，我既想把js放到本地host上，又不想引入辅助插件。于是我手动去弄：
1）从MathJax的官方仓库里下到MathJax最新的release，注意要下3.X版本的。
"Version 4.0 changes the version of MathJax used to version 3"， 这是sphinx文档里面的话。包内容大致如下：
2）es5文件夹拷贝到build/_static文件夹下
3）配置mathjax_path为相对路径"es5/mathjax/tex-chtml.js"，其中这个相对路径是相对于build/_static文件夹的。
“The path can be absolute or relative; if it is relative, it is relative to the _static directory of the built docs.”这也是文档中的话。
别问为什么用相对路径，因为绝对路径不work。
这样配置好之后，web页面应该就能正常渲染数学公式了。
其他还踩了一些坑，比如使用MathJax2.X，使用apt-get安装MathJax，比如es5这个文件夹不放在_static下就不work。当然读者可以自己尝试其他更好的做法，只是比较花时间... 还是那句话，sphinx doc其实对于支持mathjax没有交代的那么好。
标签：Sphinx,doc,js,mathjax,文档,MathJax,sphinx 来源： https://www.cnblogs.com/chester-cs/p/15929350.html