Sphinx 中 HTML 輸出的數學支援¶

在版本 0.5 中新增。

在版本 1.8 中變更：非 HTML 建構器的數學支援已整合到 sphinx-core 中。因此不再需要 mathbase 擴充功能。

由於 HTML 本身不以任何方式原生支援數學符號，Sphinx 透過數個擴充功能為 HTML 文件提供數學支援。這些擴充功能使用 reStructuredText 數學 指令 和 角色。

`sphinx.ext.imgmath` – 將數學式渲染為圖片¶

在版本 1.4 中新增。

此擴充功能透過 LaTeX 和 dvipng 或 dvisvgm 將數學式渲染為 PNG 或 SVG 圖片。這當然表示建構文件的電腦必須同時具備這兩個程式。

您可以設定各種設定值來影響圖片的建構方式

imgmath_image_format¶

類型:: 'png' | 'svg'
預設:: 'png'

輸出圖片格式。應為 'png' 或 'svg'。圖片的產生方式為先在 TeX 數學標記上執行 latex，然後 (取決於要求的格式) 使用 dvipng 或 dvisvgm。

imgmath_use_preview¶

類型:: bool
預設:: False

dvipng 和 dvisvgm 都具有從 LaTeX 收集渲染數學式的「深度」的能力：行內圖片應在 vertical-align 樣式中使用此「深度」，以與周圍文字正確對齊。

此機制需要 LaTeX preview 套件 (在 Ubuntu xenial 上以 preview-latex-style 提供)。因此，此選項的預設值為 False，但強烈建議將其設定為 True。

在版本 2.2 中變更：此選項可與 'svg' imgmath_image_format 搭配使用。

imgmath_add_tooltips¶

類型:: bool
預設:: True

如果為 false，則不要將 LaTeX 程式碼新增為數學圖片的「alt」屬性。

imgmath_font_size¶

類型:: int
預設:: 12

顯示的數學式的字型大小 (以 pt 為單位)。這必須是正整數。

imgmath_latex¶

類型:: str
預設:: 'latex'

用來叫用 LaTeX 的命令名稱。如果 latex 不在可執行檔搜尋路徑中，您可能需要將此設定為完整路徑。

由於此設定在系統之間不可攜，因此通常不適合在 conf.py 中設定；而是應透過 -D 選項在 sphinx-build 命令列上提供，如下所示

sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build

此值應僅包含 latex 可執行檔的路徑，不包含其他引數；請改用 imgmath_latex_args。

提示

若要搭配 OpenType Math 字型和 unicode-math，透過自訂 imgmath_latex_preamble，您可以將 imgmath_latex 設定為 'dvilualatex'，但接著必須將 imgmath_image_format 設定為 'svg'。注意：這僅在 dvisvgm 3.0.3 上測試過。與使用標準 'latex' 和傳統 TeX 數學字型相比，這會大幅增加圖片產生持續時間。

提示

某些精美的 LaTeX 標記 (回報的範例使用 TikZ 將各種裝飾新增至方程式) 需要多次執行 LaTeX 可執行檔。若要處理此問題，請將此設定設定為 'latexmk' (或其完整路徑)，因為此 Perl 指令碼會可靠地動態選擇需要執行多少次 latex。

在版本 6.2.0 中變更：現在支援使用 'xelatex' (或其完整路徑)。但您接著必須將 '-no-pdf' 新增至 imgmath_latex_args 命令選項清單。'svg' imgmath_image_format 為必要項目。此外，您可能需要相對較新的 dvisvgm 二進位檔 (測試僅使用其 3.0.3 版本完成)。

注意

關於先前的注意事項，目前不支援將 latexmk 與選項 -xelatex 搭配使用。

imgmath_latex_args¶

類型:: Sequence[str]
預設:: ()

要提供給 latex 的其他引數，以清單形式呈現。

imgmath_latex_preamble¶

類型:: str
預設:: ''

要放入 LaTeX 檔案前言的其他 LaTeX 程式碼，用於轉換數學片段。例如，使用它來新增套件，以修改用於數學式的字型，例如用於 sans-serif 字型的 '\\usepackage{newtxsf}'，或用於 serif 字型的 '\\usepackage{fouriernc}'。實際上，預設的 LaTeX 數學字型具有相當細的字符，這些字符 (在 HTML 輸出中) 通常與文字的字型不太相符。

imgmath_dvipng¶

類型:: str
預設:: 'dvipng'

要叫用 dvipng 的命令名稱。如果 dvipng 不在可執行檔搜尋路徑中，您可能需要將此設定為完整路徑。僅當 imgmath_image_format 設定為 'png' 時，才會使用此選項。

imgmath_dvipng_args¶

類型:: Sequence[str]
預設:: ('-gamma', '1.5', '-D', '110', '-bg', 'Transparent')

要提供給 dvipng 的其他引數，以清單形式呈現。預設值會使圖片比預設情況稍暗且稍大 (這會在某種程度上彌補預設 LaTeX 數學字型的細緻度)，並產生具有透明背景的 PNG。僅當 imgmath_image_format 為 'png' 時，才會使用此選項。

imgmath_dvisvgm¶

類型:: str
預設:: 'dvisvgm'

要叫用 dvisvgm 的命令名稱。如果 dvisvgm 不在可執行檔搜尋路徑中，您可能需要將此設定為完整路徑。僅當 imgmath_image_format 為 'svg' 時，才會使用此選項。

imgmath_dvisvgm_args¶

類型:: Sequence[str]
預設:: ('--no-fonts',)

要提供給 dvisvgm 的其他引數，以清單形式呈現。預設值表示 dvisvgm 會將字符渲染為路徑元素 (請參閱 dvisvgm FAQ)。僅當 imgmath_image_format 為 'svg' 時，才會使用此選項。

imgmath_embed¶

類型:: bool
預設:: False

如果為 true，則將 LaTeX 輸出圖片編碼在 HTML 檔案內 (base64 編碼)，且不將個別的 png/svg 檔案儲存到磁碟。

在版本 5.2 中新增。

`sphinx.ext.mathjax` – 透過 JavaScript 渲染數學式¶

警告

版本 4.0 將使用的 MathJax 版本變更為版本 3。您可能需要覆寫 mathjax_path 為 https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML，或更新版本 3 的設定選項 (請參閱 mathjax3_config)。

在版本 1.1 中新增。

此擴充功能將數學式原封不動地放入 HTML 檔案中。接著載入 JavaScript 套件 MathJax，並在瀏覽器中即時將 LaTeX 標記轉換為可讀的數學式。

由於 MathJax (和必要的字型) 非常大，因此未包含在 Sphinx 中，而是設定為從協力廠商網站自動包含它。

注意

您應該使用 math 指令 和 角色，而不是原生的 MathJax $$、 等。

mathjax_path¶

類型:: str
預設:: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

要包含在 HTML 檔案中以載入 MathJax 的 JavaScript 檔案路徑。

預設值為 https:// URL，其從 jsdelivr 內容傳遞網路載入 JS 檔案。如需詳細資訊，請參閱 MathJax 入門頁面。如果您希望 MathJax 能夠離線使用，或在不包含協力廠商網站資源的情況下使用，則必須下載它並將此值設定為不同的路徑。

路徑可以是絕對路徑或相對路徑；如果是相對路徑，則相對於建構文件的 _static 目錄。

例如，如果您將 MathJax 放入 Sphinx 文件的靜態路徑中，則此值會是 MathJax/MathJax.js。如果您在一部伺服器上託管多個 Sphinx 文件集，建議將 MathJax 安裝在共用位置。

您也可以提供與 CDN URL 不同的完整 https:// URL。

mathjax_options¶

類型:: dict[str, Any]
預設:: {}

mathjax 腳本標籤的選項。例如，您可以使用以下設定設定完整性選項

mathjax_options = {
    'integrity': 'sha384-......',
}

在版本 1.8 中新增。

在版本 4.4.1 中變更：如果設定「async」或「defer」索引鍵，則允許變更 MathJax 的載入方法 (async 或 defer)。

mathjax3_config¶

類型:: dict[str, Any] | None
預設:: None

MathJax v3 (預設使用) 的設定選項。給定的字典會指派給 JavaScript 變數 window.MathJax。如需更多資訊，請參閱設定 MathJax。

在版本 4.0 中新增。

mathjax2_config¶

類型:: dict[str, Any] | None
預設:: None

MathJax v2 (可透過 mathjax_path 載入) 的設定選項。此值會用作 MathJax.Hub.Config() 的參數。如需更多資訊，請參閱使用行內設定選項。

例如

mathjax2_config = {
    'extensions': ['tex2jax.js'],
    'jax': ['input/TeX', 'output/HTML-CSS'],
}

在版本 4.0 中新增：mathjax_config 已重新命名為 mathjax2_config。

mathjax_config¶

類型:: dict[str, Any] | None
預設:: None

mathjax2_config 的舊名稱。

如需將舊版 MathJax 設定轉換為新的 mathjax3_config 的協助，請參閱將您的 v2 設定轉換為 v3。

在版本 1.8 中新增。

在版本 4.0 中變更：這已重新命名為 mathjax2_config。mathjax_config 仍受支援以實現回溯相容性。

`sphinx.ext.jsmath` – 透過 JavaScript 渲染數學式¶

此擴充功能的作用與 MathJax 擴充功能相同，但使用較舊的套件 jsMath。它提供此設定值

jsmath_path¶

類型:: str
預設:: ''

要包含在 HTML 檔案中以載入 JSMath 的 JavaScript 檔案路徑。

路徑可以是絕對路徑或相對路徑；如果是相對路徑，則相對於建構文件的 _static 目錄。

例如，如果您將 JSMath 放入 Sphinx 文件的靜態路徑中，則此值會是 jsMath/easy/load.js。如果您在一部伺服器上託管多個 Sphinx 文件集，建議將 jsMath 安裝在共用位置。

Sphinx 中 HTML 輸出的數學支援¶

sphinx.ext.imgmath – 將數學式渲染為圖片¶

sphinx.ext.mathjax – 透過 JavaScript 渲染數學式¶

sphinx.ext.jsmath – 透過 JavaScript 渲染數學式¶

`sphinx.ext.imgmath` – 將數學式渲染為圖片¶

`sphinx.ext.mathjax` – 透過 JavaScript 渲染數學式¶

`sphinx.ext.jsmath` – 透過 JavaScript 渲染數學式¶