标签：Sphinx doc js mathjax 文档 MathJax sphinx
参考资料：
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
本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享； 2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关； 3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关； 4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除； 5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。