如何讓Sphinx doc支援MathJax公式

實現這個目的難嗎？一點都不難，但是sphinx是以擴充套件的形式來支援mathjax數學公式渲染的，並且坦白地說，它支援的一點都不好。下面是我自己摸索的操作步驟，花了不少時間，因為中英文**上關於sphinx doc支援mathjax的tutorial基本沒有。

1. 直接配置外掛程式即可

按照參考資料2的文件中的做法，我們必須在sphinx doc目錄下的conf.py檔案中的extensions列表裡加上乙個字串：『sphinx.ext.mathjax』

extensions = [
'sphinx.ext.mathjax'
]

加上這個字串之後，使用make html重新編譯web頁面，有一定的概率你的**已經正確地把latex公式渲染出來了。

mathjax_path = ''

2. 使用輔助外掛程式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_staticdirectory of the built docs.」這也是文件中的話。

別問為什麼用相對路徑，因為絕對路徑不work。

這樣配置好之後，web頁面應該就能正常渲染數學公式了。

其他還踩了一些坑，比如使用mathjax2.x，使用apt-get安裝mathjax，比如es5這個資料夾不放在_static下就不work。當然讀者可以自己嘗試其他更好的做法，只是比較花時間... 還是那句話，sphinx doc其實對於支援mathjax沒有交代的那麼好。