設定¶

設定目錄必須包含一個名為 conf.py 的檔案。此檔案（包含 Python 程式碼）被稱為「建置設定檔」，並且包含（幾乎）所有自訂 Sphinx 輸入和輸出行為所需的設定。

一個可選的檔案 docutils.conf 可以被添加到設定目錄中，以調整 Docutils 設定，如果沒有被 Sphinx 覆蓋或設定。

重要注意事項

如果沒有另行說明，值必須是字串，且預設值為空字串。
術語「完整限定名稱」（FQN）指的是一個字串，該字串命名一個模組內可導入的 Python 物件；例如，完整限定名稱 "sphinx.builders.Builder" 意指 sphinx.builders 模組中的 Builder 類別。
文件名稱使用 / 作為路徑分隔符，並且不包含檔案名稱副檔名。

在允許 glob 風格模式的地方，您可以使用標準 shell 結構（*、?、[...] 和 [!...]），但這些都不會匹配斜線 (/)。雙星號 ** 可以用來匹配任何字元序列，包括斜線。

提示

設定檔在建置時作為 Python 程式碼執行（使用 importlib.import_module()，並將當前目錄設定為設定目錄），因此可以執行任意複雜的程式碼。

然後，Sphinx 從檔案的命名空間中讀取簡單的名稱作為其設定。一般來說，設定值應該是簡單的字串、數字，或簡單值的列表或字典。

設定命名空間的內容會被 pickled（以便 Sphinx 可以找出設定何時變更），因此它可能不包含無法 pickled 的值 – 如果合適，請使用 del 從命名空間中刪除它們。模組會自動移除，因此不需要刪除導入的模組。

專案標籤¶

在設定檔中有一個名為 tags 的特殊物件，它公開了專案標籤。標籤可以透過 --tag 命令行選項或 tags.add('tag') 定義。請注意，建構器的名稱和格式標籤在 conf.py 中不可用。

它可以如下所示用於查詢和變更已定義的標籤

若要查詢是否已設定標籤，請使用 'tag' in tags。
若要新增標籤，請使用 tags.add('tag')。
若要移除標籤，請使用 tags.remove('tag')。

專案資訊¶

project¶

類型:: 字串
預設:: '未設定專案名稱'

已記錄專案的名稱。範例

project = 'Thermidor'

author¶

類型:: 字串
預設:: '未設定作者名稱'

專案的作者。範例

author = 'Joe Bloggs'

copyright¶

project_copyright¶

類型:: str | Sequence[str]
預設:: ''

copyright = 'YYYY'
copyright = 'YYYY, Author Name'
copyright = 'YYYY Author Name'
copyright = 'YYYY-YYYY, Author Name'
copyright = 'YYYY-YYYY Author Name'

如果字串 '%Y' 出現在版權行中，它將被替換為當前的四位數年份。例如

copyright = '%Y'
copyright = '%Y, Author Name'
copyright = 'YYYY-%Y, Author Name'

Added in version 3.5: project_copyright 別名。

version¶

類型:: 字串
預設:: ''

主要專案版本，用作 |version| 預設替換的替換值。

這可能類似於 version = '4.2'。完整的專案版本在 release 中定義。

如果您的專案在「完整」和「主要」版本之間沒有有意義的區別，請將 version 和 release 都設定為相同的值。

release¶

類型:: 字串
預設:: ''

完整的專案版本，用作 |release| 預設替換的替換值，例如在 HTML 模板中。

這可能類似於 release = '4.2.1b0'。主要（簡短）專案版本在 version 中定義。

如果您的專案在「完整」和「主要」版本之間沒有有意義的區別，請將 version 和 release 都設定為相同的值。

一般設定¶

needs_sphinx¶

類型:: 字串
預設:: ''

設定建置專案所需的 Sphinx 最低支援版本。格式應為 'major.minor' 版本字串，例如 '1.1'。Sphinx 會將其與自身版本進行比較，如果執行的 Sphinx 版本太舊，則會拒絕建置專案。預設情況下，沒有最低版本。

Added in version 1.0.

Changed in version 1.4: 允許 'major.minor.micro' 版本字串。

extensions¶

類型:: list[str]
預設:: []

字串列表，這些字串是 Sphinx 擴充功能的模組名稱。這些可以是與 Sphinx 捆綁在一起的擴充功能（命名為 sphinx.ext.*），或是自訂的第一方或第三方擴充功能。

若要使用第三方擴充功能，您必須確保已安裝它並將其包含在 extensions 列表中，如下所示

extensions = [
    ...
    'numpydoc',
]

對於第一方擴充功能，有兩個選項。設定檔本身可以是一個擴充功能；對於這種情況，您只需要在其中提供一個 setup() 函數。否則，您必須確保您的自訂擴充功能是可導入的，並且位於 Python 路徑中的目錄中。

在修改 sys.path 時，請確保使用絕對路徑。如果您的自訂擴充功能位於相對於設定目錄的目錄中，請使用 pathlib.Path.resolve()，如下所示

import sys
from pathlib import Path

sys.path.append(str(Path('sphinxext').resolve()))

extensions = [
   ...
   'extname',
]

上面說明的目錄結構如下所示

<project directory>/
├── conf.py
└── sphinxext/
    └── extname.py

needs_extensions¶

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

如果設定，則此值必須是一個字典，指定 extensions 中擴充功能的版本要求。版本字串應為 'major.minor' 形式。不必為所有擴充功能指定要求，只需為您要檢查的擴充功能指定即可。範例

needs_extensions = {
    'sphinxcontrib.something': '1.5',
}

這要求擴充功能在其 setup() 函數中宣告其版本。有關更多詳細資訊，請參閱 Sphinx API。

Added in version 1.3.

manpages_url¶

類型:: 字串
預設:: ''

用於交叉參考 manpage 角色的 URL。如果將其定義為 https://manpages.debian.org/{path}，則 :manpage:`man(1)` 角色將連結到 <https://manpages.debian.org/man(1)>。可用的模式有

頁面: 手冊頁面 (man)
區段: 手冊區段 (1)
路徑: 原始手冊頁面和指定的區段 (man(1))

這也支援指定為 man.1 的手冊頁面。

# To use manpages.debian.org:
manpages_url = 'https://manpages.debian.org/{path}'
# To use man7.org:
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
# To use linux.die.net:
manpages_url = 'https://linux.die.net/man/{section}/{page}'
# To use helpmanual.io:
manpages_url = 'https://helpmanual.io/man{section}/{page}'

Added in version 1.7.

today¶

today_fmt¶

這些值決定如何格式化當前日期，用作 |today| 預設替換的替換值。

如果您將 today 設定為非空值，則會使用它。
否則，當前時間將使用 time.strftime() 和 today_fmt 中給定的格式進行格式化。

today 的預設值為 ''，而 today_fmt 的預設值為 '%b %d, %Y'（或者，如果透過 language 啟用翻譯，則為選定地區設定的等效格式）。

圖片編號選項¶

numfig¶

類型:: bool
預設:: False

如果為 True，則如果圖片、表格和程式碼區塊有標題，它們將自動編號。numref 角色已啟用。目前僅 HTML 和 LaTeX 建構器遵循此設定。

注意

無論是否啟用此選項，LaTeX 建構器始終會分配編號。

Added in version 1.3.

numfig_format¶

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

一個字典，將 'figure'、'table'、'code-block' 和 'section' 對應到用於圖片編號格式的字串。標記 %s 將被替換為圖片編號。

預設值為

numfig_format = {
    'code-block': 'Listing %s',
    'figure': 'Fig. %s',
    'section': 'Section',
    'table': 'Table %s',
}

Added in version 1.3.

numfig_secnum_depth¶

類型:: int
預設:: 1

如果設定為 0，則圖片、表格和程式碼區塊會從 1 開始連續編號。
如果為 1，則編號將為 x.1、x.2、…，其中 x 代表章節編號。（如果沒有頂層章節，則不會新增前綴）。這自然僅在章節編號已透過 toctree 指令的 :numbered: 選項啟用的情況下適用。
如果為 2，則編號將為 x.y.1、x.y.2、…，其中 x 代表章節編號，而 y 代表子章節編號。如果直接位於章節下，則不會有 y. 前綴，並且如果沒有頂層章節，則不會新增前綴。
可以使用任何其他正整數，並遵循上述規則。

Added in version 1.3.

Changed in version 1.7: 如果 numfig 設定為 True，則 LaTeX 建構器會遵循此設定。

程式碼高亮選項¶

highlight_language¶

類型:: 字串
預設:: 'default'

用於程式碼高亮的預設語言。預設值為 'default'，如果以 Python 程式碼高亮失敗，則會抑制警告。

值應為有效的 Pygments 詞法分析器名稱，有關更多詳細資訊，請參閱顯示程式碼範例。

Added in version 0.5.

Changed in version 1.4: 預設值現在為 'default'。

highlight_options¶

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

一個字典，將 Pygments 詞法分析器名稱對應到它們的選項。這些是詞法分析器特定的；對於每個詞法分析器理解的選項，請參閱 Pygments 文件。

範例

highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

Added in version 1.3.

Changed in version 3.5: 允許為多個詞法分析器配置高亮選項。

pygments_style¶

類型:: 字串
預設:: 'sphinx'

用於 Pygments 程式碼高亮的樣式名稱。如果未設定，則會為 HTML 輸出選擇主題的預設樣式或 'sphinx'。

Changed in version 0.3: 如果值是自訂 Pygments 樣式類別的完整限定名稱，則將其用作自訂樣式。

HTTP 請求選項¶

tls_verify¶

類型:: bool
預設:: True

如果為 True，則 Sphinx 會驗證伺服器憑證。

Added in version 1.5.

tls_cacerts¶

類型:: str | dict[str, str]
預設:: ''

CA 憑證檔案的路徑，或包含憑證的目錄的路徑。這也允許使用字典將主機名稱對應到憑證檔案路徑。憑證用於驗證伺服器憑證。

Added in version 1.5.

提示

Sphinx 在內部使用 requests 作為 HTTP 函式庫。如果未設定 tls_cacerts，Sphinx 將回退到 requests 的預設行為。有關更多詳細資訊，請參閱 SSL 憑證驗證。

user_agent¶

類型:: 字串
預設:: 'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 Sphinx/X.Y.Z'

設定 Sphinx 用於 HTTP 請求的 User-Agent。

Added in version 2.3.

國際化選項¶

這些選項影響 Sphinx 的原生語言支援。有關詳細資訊，請參閱關於國際化的文件。

language¶

類型:: 字串
預設:: 'en'

此設定為文件撰寫時所使用的語言代碼。Sphinx 自動產生的任何文字都會使用此語言。此外，Sphinx 也會嘗試將您的文件中個別的段落，替換成從 locale_dirs 取得的翻譯集。Sphinx 將會搜尋以 figure_language_filename 命名的特定語言圖片 (例如，myfigure.png 的德文版本預設設定會是 myfigure.de.png)，並將它們替換成原始圖片。在 LaTeX 產生器中，將會選取合適的語言作為 Babel 套件的選項。

Added in version 0.5.

版本 1.4 更新: 支援圖片替換

版本 5.0 更新: 預設值現在為 'en' (先前為 None)。

目前 Sphinx 支援的語言有

ar – 阿拉伯文
bg – 保加利亞文
bn – 孟加拉文
ca – 加泰隆尼亞文
cak – 卡克奇克爾語
cs – 捷克文
cy – 威爾斯文
da – 丹麥文
de – 德文
el – 希臘文
en – 英文 (預設)
eo – 世界語
es – 西班牙文
et – 愛沙尼亞文
eu – 巴斯克文
fa – 伊朗文
fi – 芬蘭文
fr – 法文
he – 希伯來文
hi – 印地文
hi_IN – 印地文 (印度)
hr – 克羅埃西亞文
hu – 匈牙利文
id – 印尼文
it – 義大利文
ja – 日文
ko – 韓文
lt – 立陶宛文
lv – 拉脫維亞文
mk – 馬其頓文
nb_NO – 書面挪威文
ne – 尼泊爾文
nl – 荷蘭文
pl – 波蘭文
pt – 葡萄牙文
pt_BR – 巴西葡萄牙文
pt_PT – 歐洲葡萄牙文
ro – 羅馬尼亞文
ru – 俄文
si – 僧伽羅文
sk – 斯洛伐克文
sl – 斯洛維尼亞文
sq – 阿爾巴尼亞文
sr – 塞爾維亞文
sr@latin – 塞爾維亞文 (拉丁文)
sr_RS – 塞爾維亞文 (西里爾文)
sv – 瑞典文
ta – 泰米爾文
te – 泰盧固文
tr – 土耳其文
uk_UA – 烏克蘭文
ur – 烏爾都文
vi – 越南文
zh_CN – 簡體中文
zh_TW – 繁體中文

locale_dirs¶

類型:: list[str]
預設:: ['locales']

在其中搜尋額外訊息目錄的目錄 (請參閱 language)，相對於來源目錄。此路徑上的目錄會由 gettext 模組搜尋。

內部訊息會從 sphinx 的文字網域中提取；因此，如果您將目錄 ./locales 新增至此設定，則訊息目錄 (從使用 msgfmt 從 .po 格式編譯而來) 必須位於 ./locales/language/LC_MESSAGES/sphinx.mo 中。個別文件的文字網域取決於 gettext_compact。

注意

-v 選項到 sphinx-build 對於檢查 locale_dirs 設定是否如預期運作非常有用。如果找不到訊息目錄，則會發出偵錯訊息。

Added in version 0.5.

版本 1.5 更新: 使用 locales 目錄作為預設值

gettext_allow_fuzzy_translations¶

類型:: bool
預設:: False

如果為 True，則訊息目錄中「模糊」的訊息會用於翻譯。

版本 4.3 新增。

gettext_compact¶

類型:: bool | str
預設:: True

如果為 True，則文件的文字網域會是其 docname (如果它是頂層專案檔案)，否則會是其最上層目錄。
如果為 False，則文件的文字網域會是完整的 docname。
如果設定為字串，則每個文件的文字網域都會設定為此字串，使所有文件都使用單一文字網域。

使用 gettext_compact = True，文件 markup/code.rst 會在 markup 文字網域中結束。如果此選項設定為 False，則為 markup/code。如果此選項設定為 'sample'，則為 sample。

版本 1.1 新增。

版本 3.3 更新: 允許字串值。

gettext_uuid¶

類型:: bool
預設:: False

如果為 True，Sphinx 會在訊息目錄中產生 UUID 資訊以進行版本追蹤。它用於

在 .pot 檔案中為每個 msgid 新增 UUID 行。
計算新 msgid 與先前儲存的舊 msgid 之間的相似度。(此計算可能需要很長時間。)

提示

如果您想加速計算，可以使用第三方套件 (Levenshtein)，方法是執行 pip install levenshtein。

Added in version 1.3.

gettext_location¶

類型:: bool
預設:: True

如果為 True，Sphinx 會在訊息目錄中產生訊息的位置資訊。

Added in version 1.3.

gettext_auto_build¶

類型:: bool
預設:: True

如果為 True，Sphinx 會為每個翻譯目錄檔案建置 .mo 檔案。

Added in version 1.3.

gettext_additional_targets¶

類型:: set[str] | Sequence[str]
預設:: []

為某些元素類型啟用 gettext 翻譯。範例

gettext_additional_targets = {'literal-block', 'image'}

支援下列元素類型

'index' – 索引詞彙
'literal-block' – 文字區塊 (:: 註解和 code-block 指令)
'doctest-block' – doctest 區塊
'raw' – 原始內容
'image' – 圖片/圖表 URI

Added in version 1.3.

版本 4.0 更新: 預設會翻譯圖片的替代文字。

版本 7.4 更新: 允許並偏好 set 類型。

figure_language_filename¶

類型:: 字串
預設:: '{root}.{language}{ext}'

特定語言圖片的檔案名稱格式。可用的格式符記為

{root}: 檔案名稱，包含任何路徑元件，但不含副檔名。例如：images/filename。
{path}: 檔案名稱的目錄路徑元件，如果非空則帶有尾部斜線。例如：images/。
{basename}: 不含目錄路徑或副檔名元件的檔案名稱。例如：filename。
{ext}: 副檔名。例如：.png。
{language}: 翻譯語言。例如：en。
{docpath}: 目前文件的目錄路徑元件，如果非空則帶有尾部斜線。例如：dirname/。

預設情況下，圖片指令 .. image:: images/filename.png，使用位於 images/filename.png 的圖片，將會使用特定語言的圖片檔案名稱 images/filename.en.png。

如果 figure_language_filename 設定如下，則特定語言的圖片檔案名稱將會是 images/en/filename.png。

figure_language_filename = '{path}{language}/{basename}{ext}'

版本 1.4 新增。

版本 1.5 更新: 新增 {path} 和 {basename} 符記。

版本 3.2 更新: 新增 {docpath} 符記。

translation_progress_classes¶

類型:: bool | 'translated' | 'untranslated'
預設:: False

控制是否新增任何類別來指示翻譯進度。此設定可能僅供文件翻譯人員使用，以便快速指示已翻譯和未翻譯的內容。

True: 將 translated 和 untranslated 類別新增至所有具有可翻譯內容的節點。
'translated': 僅新增 translated 類別。
'untranslated': 僅新增 untranslated 類別。
False: 不新增任何類別來指示翻譯進度。

版本 7.1 新增。

標記選項¶

default_role¶

類型:: 字串
預設:: None

要用作預設角色的 reStructuredText 角色名稱 (內建或 Sphinx 擴充功能)，也就是用於標記為 `像這樣` 的文字。可以將其設定為 'py:obj'，以使 `filter` 成為對 Python 函數 "filter" 的交叉參照。

預設角色始終可以使用標準 reStructuredText default-role 指令在個別文件中設定。

版本 0.4 新增。

keep_warnings¶

類型:: bool
預設:: False

將警告保留為呈現文件中的「系統訊息」段落。無論此設定為何，當執行 sphinx-build 時，警告始終會寫入標準錯誤流。

Added in version 0.5.

option_emphasise_placeholders¶

類型:: bool
預設:: False

啟用時，強調 option 指令中的預留位置。若要顯示文字大括號，請使用反斜線 (\{) 逸出。例如，option_emphasise_placeholders=True 和 .. option:: -foption={TYPE} 將會呈現強調顯示 TYPE。

版本 5.1 新增。

primary_domain¶

類型:: 字串
預設:: 'py'

預設網域的名稱。也可以是 None 以停用預設網域。預設值為 'py'，適用於 Python 網域。

其他網域中的那些物件 (無論網域名稱是明確給定，還是由 default-domain 指令選取) 在命名時將會明確地加上網域名稱前綴 (例如，當預設網域為 C 時，Python 函數將會命名為「Python 函數」，而不僅僅是「函數」)。範例

primary_domain = 'cpp'

Added in version 1.0.

rst_epilog¶

類型:: 字串
預設:: ''

一個 reStructuredText 字串，將會包含在每個讀取的來源檔案的結尾。這是一個可能新增應該在每個檔案中都可用的替換 (另一個是 rst_prolog) 的位置。範例

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

版本 0.6 新增。

rst_prolog¶

類型:: 字串
預設:: ''

一個 reStructuredText 字串，將會包含在每個讀取的來源檔案的開頭。這是一個可能新增應該在每個檔案中都可用的替換 (另一個是 rst_epilog) 的位置。範例

rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""

Added in version 1.0.

show_authors¶

類型:: bool
預設:: False

一個布林值，決定 codeauthor 和 sectionauthor 指令是否在已建置的檔案中產生任何輸出。

trim_footnote_reference_space¶

類型:: bool
預設:: False

修剪註腳參照之前的空格，這些空格是 reStructuredText 解析器辨識註腳所必需的，但在輸出中看起來不太美觀。

版本 0.6 新增。

數學選項¶

這些選項控制數學標記和符號。

math_eqref_format¶

類型:: 字串
預設:: '({number})'

用於格式化方程式參照標籤的字串。{number} 預留位置代表方程式編號。

範例：'Eq.{number}' 會呈現為，例如，Eq.10。

Added in version 1.7.

math_number_all¶

類型:: bool
預設:: False

強制所有顯示的方程式都編號。範例

math_number_all = True

版本 1.4 新增。

math_numfig¶

類型:: bool
預設:: True

如果為 True，則當啟用 numfig 時，顯示的數學方程式會在頁面之間編號。numfig_secnum_depth 設定會被遵守。必須使用 eq 角色，而不是 numref 角色來參照方程式編號。

Added in version 1.7.

math_numsep¶

類型:: 字串
預設:: '.'

一個字串，定義當啟用 numfig 且 numfig_secnum_depth 為正數時，章節編號與方程式編號之間的分隔符號。

範例：'-' 會呈現為 1.2-3。

版本 7.4 新增。

吹毛求疵模式選項¶

nitpicky¶

類型:: bool
預設:: False

如果為 True，則啟用吹毛求疵模式。在吹毛求疵模式下，Sphinx 會警告所有找不到目標的參照。建議新專案使用此模式，因為它可以確保所有參照都指向有效的目標。

您可以使用 --nitpicky 命令列選項暫時啟用此模式。請參閱 nitpick_ignore，以了解如何將遺失的參照標記為「已知遺失」。

nitpicky = True

Added in version 1.0.

nitpick_ignore¶

類型:: set[tuple[str, str]] | Sequence[tuple[str, str]]
預設:: ()

一組或清單的 (warning_type, target) 元組，在 "吹毛求疵模式" 中產生警告時應忽略。請注意，如果存在網域，warning_type 應包含網域名稱。範例

nitpick_ignore = {
    ('py:func', 'int'),
    ('envvar', 'LD_LIBRARY_PATH'),
}

版本 1.1 新增。

版本 6.2 更新: 將允許的容器類型變更為 set、list 或 tuple

nitpick_ignore_regex¶

類型:: set[tuple[str, str]] | Sequence[tuple[str, str]]
預設:: ()

擴充版本的 nitpick_ignore，它將 warning_type 和 target 字串解譯為正則表達式。請注意，正則表達式必須符合整個字串 (如同插入了 ^ 和 $ 標記)。

例如，(r'py:.*', r'foo.*bar\.B.*') 將忽略所有以 'foo' 開頭且包含 'bar.B' 的 Python 實體的吹毛求疵警告，例如 ('py:const', 'foo_package.bar.BAZ_VALUE') 或 ('py:class', 'food.bar.Barman')。

版本 4.1 新增。

版本 6.2 更新: 將允許的容器類型變更為 set、list 或 tuple

物件簽名選項¶

add_function_parentheses¶

類型:: bool
預設:: True

一個布林值，決定是否將括號附加到函數和方法角色文字 (例如 :func:`input` 的內容)，以表示該名稱是可呼叫的。

maximum_signature_line_length¶

類型:: int | None
預設:: None

如果簽名的字元長度超過設定的數字，則簽名中的每個參數都會顯示在個別的邏輯行上。

當 None 時，沒有最大長度，整個簽名將會顯示在單一邏輯行上。

「邏輯行」類似於硬換行符號—產生器或佈景主題可能會選擇「軟換行」單一邏輯行，而此設定不會影響該行為。

網域可能會提供選項來抑制個別物件指令上的任何硬換行，例如在 C、C++ 和 Python 網域中看到的 (例如 py:function:single-line-parameter-list)。

版本 7.1 新增。

strip_signature_backslash¶

類型:: bool
預設:: False

當啟用反斜線移除功能時，網域指令中每次出現的 \\ 都會被變更為 \，即使在字串文字內也是如此。這是 3.0 版本之前的行為，將此變數設定為 True 將會恢復該行為。

在 3.0 版本中新增。

toc_object_entries¶

類型:: bool
預設:: True

為網域物件 (例如：函式、類別、屬性等等) 建立目錄條目。

在 5.2 版本中新增。

toc_object_entries_show_parents¶

類型:: 'domain' | 'hide' | 'all'
預設:: 'domain'

一個字串，用於決定網域物件 (函式、類別、屬性等等) 在其目錄條目中如何顯示。

使用 'domain' 以允許網域決定要顯示的父層級數量。例如，Python 網域會顯示 Class.method() 和 function()，而省略 module. 父層級。

使用 'hide' 以僅顯示元素的名稱，而不顯示任何父層級 (即 method())。

使用 'all' 以顯示物件的完整限定名稱 (即 module.Class.method())，顯示所有父層級。

在 5.2 版本中新增。

原始檔選項¶

exclude_patterns¶

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

在尋找原始檔時，應排除的 glob 樣式模式清單。它們會根據相對於原始目錄的原始檔名進行比對，並在所有平台上使用斜線作為目錄分隔符號。exclude_patterns 的優先順序高於 include_patterns。

範例模式

'library/xml.rst' – 忽略 library/xml.rst 檔案
'library/xml' – 忽略 library/xml 目錄
'library/xml*' – 忽略所有以 library/xml 開頭的檔案和目錄
'**/.git' – 忽略所有 .git 目錄
'Thumbs.db' – 忽略所有 Thumbs.db 檔案

當在 html_static_path 和 html_extra_path 中尋找靜態檔案時，也會參考 exclude_patterns。

Added in version 1.0.

include_patterns¶

類型:: Sequence[str]
預設:: ('**',)

用於尋找原始檔的 glob 樣式模式清單。它們會根據相對於原始目錄的原始檔名進行比對，並在所有平台上使用斜線作為目錄分隔符號。預設情況下，所有檔案都會從原始目錄以遞迴方式包含。exclude_patterns 的優先順序高於 include_patterns。

範例模式

'**' – 原始目錄和子目錄中的所有檔案，以遞迴方式包含
'library/xml' – 僅 library/xml 目錄
'library/xml*' – 所有以 library/xml 開頭的檔案和目錄
'**/doc' – 所有 doc 目錄 (如果文件與原始檔位於相同位置，這可能會很有用)

版本 5.1 新增。

master_doc¶

root_doc¶

類型:: 字串
預設:: 'index'

Sphinx 根據原始檔中包含的 toctree 指令建立文件樹狀結構。這會設定包含主要 toctree 指令的文件名稱，進而成為整個樹狀結構的根目錄。範例

master_doc = 'contents'

在 2.0 版本中變更：預設值為 'index' (先前為 'contents')。

在 4.0 版本中新增： root_doc 別名。

source_encoding¶

類型:: 字串
預設:: 'utf-8-sig'

所有原始檔的檔案編碼。建議的編碼為 'utf-8-sig'。

Added in version 0.5.

source_suffix¶

類型:: dict[str, str] | Sequence[str] | str
預設:: {'.rst': 'restructuredtext'}

一個字典，將原始檔的副檔名 (字尾) 對應到其檔案類型。Sphinx 將所有副檔名在 source_suffix 中的檔案視為原始檔。範例

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

預設情況下，Sphinx 僅支援 'restructuredtext' 檔案類型。可以使用註冊不同原始檔剖析器的擴充功能來新增更多檔案類型，例如 MyST-Parser。請參閱擴充功能的說明文件，以了解它支援哪些檔案類型。

如果值是字串或字串序列，Sphinx 會認為它們都是 'restructuredtext' 檔案。

注意

副檔名必須以點號 ('.') 開頭。

在 1.3 版本中變更：支援副檔名清單。

在 1.8 版本中變更：變更為副檔名到檔案類型的對應。

智能引號選項¶

smartquotes¶

類型:: bool
預設:: True

如果 True，將會使用智能引號轉換將引號和破折號轉換為印刷上正確的實體。

在 1.6.6 版本中新增：取代現已移除的 html_use_smartypants。預設情況下，它適用於除了 man 和 text 以外的所有建構器 (請參閱 smartquotes_excludes)。

注意

如果 docutils.conf 檔案位於設定目錄 (或全域 ~/.docutils 檔案) 中，且該檔案透過對應的 Docutils 選項 *停用* 了智能引號，則會無條件遵守該檔案。但如果它 *啟用* 了智能引號，則 smartquotes 設定仍然優先。

smartquotes_action¶

類型:: 字串
預設:: 'qDe'

自訂智能引號轉換。請參閱下方允許的代碼。預設的 'qDe' 會將一般**q**引號字元 "、'、em- 和 en-**D**破折號 ---、--，以及 **e**省略符號 ... 轉換為智能引號。

'q': 轉換引號
'b': 轉換反引號 (僅 ``double'')
'B': 轉換反引號 (``double'' 和 `single')
'd': 轉換破折號 (將 -- 轉換為 em 破折號，將 --- 轉換為 en 破折號)
'D': 轉換破折號 (舊式) (將 -- 轉換為 en 破折號，將 --- 轉換為 em 破折號)
'i': 轉換破折號 (反向舊式) (將 -- 轉換為 em 破折號，將 --- 轉換為 en 破折號)
'e': 轉換省略符號 ...
'w': 將 '"' 實體轉換為 '"'

在 1.6.6 版本中新增。

smartquotes_excludes¶

類型:: dict[str, list[str]]
預設:: {'languages': ['ja'], 'builders': ['man', 'text']}

控制何時停用智能引號轉換。允許的鍵為 'builders' 和 'languages'，值為字串清單。

每個條目都提供一個充分條件，以忽略 smartquotes 設定並停用智能引號轉換。範例

smartquotes_excludes = {
    'languages': ['ja'],
    'builders': ['man', 'text'],
}

注意

目前，在使用多個目標調用 make 的情況下，只有第一個目標名稱會針對 'builders' 條目進行測試，並決定所有目標的行為。此外，在 make html 之後執行 make text 時，需要以 make text SPHINXOPTS="-E" 的形式發出指令，以強制重新剖析原始檔，因為快取的原始檔已經轉換過。另一方面，直接使用 sphinx-build 不會發生此問題，因為它 (在其預設用法中) 會將剖析後的原始檔快取在每個建構器的位置。

提示

另一種有效地停用 (或自訂) 特定建構器 (例如 latex) 的智能引號的方法，是使用以下 make 方式

make latex SPHINXOPTS="-D smartquotes_action="

與先前的注意事項中的情況相反，這可以在執行 make html 之後沒有問題地執行。

在 1.6.6 版本中新增。

樣板選項¶

template_bridge¶

類型:: 字串
預設:: ''

一個字串，包含可調用物件 (或僅僅是一個類別) 的完整限定名稱，該物件會傳回 TemplateBridge 的實例。然後，此實例會用於呈現 HTML 文件，以及可能用於其他建構器的輸出 (目前為 changes 建構器)。 (請注意，如果要使用 HTML 主題，則必須讓樣板橋接器感知主題。) 範例

template_bridge = 'module.CustomTemplateBridge'

templates_path¶

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

包含額外樣板 (或覆寫內建/主題特定樣板的樣板) 的路徑清單。相對路徑會被視為相對於設定目錄的路徑。範例

templates_path = ['.templates']

在 1.3 版本中變更：由於這些檔案並非旨在建置，因此在探索原始檔時會自動排除它們。

警告控制選項¶

show_warning_types¶

類型:: bool
預設:: True

將每個警告的類型作為字尾新增到警告訊息中。例如，WARNING: [...] [index] 或 WARNING: [...] [toc.circular]。此設定可用於決定要在 suppress_warnings 清單中包含哪些警告類型。

在 7.3.0 版本中新增。

在 8.0.0 版本中變更：預設值現在為 True。

suppress_warnings¶

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

用於抑制任意警告訊息的警告代碼清單。

版本 1.4 新增。

預設情況下，Sphinx 支援以下警告代碼

app.add_directive
app.add_generic_role
app.add_node
app.add_role
app.add_source_parser
config.cache
docutils
download.not_readable
duplicate_declaration.c
duplicate_declaration.cpp
epub.duplicated_toc_entry
epub.unknown_project_files
i18n.babel
i18n.inconsistent_references
i18n.not_readable
i18n.not_writeable
image.not_readable
index
misc.copy_overwrite
misc.highlighting_failure
ref.any
ref.citation
ref.doc
ref.footnote
ref.keyword
ref.numref
ref.option
ref.python
ref.ref
ref.term
toc.circular
toc.duplicate_entry
toc.empty_glob
toc.excluded
toc.no_title
toc.not_included
toc.not_readable
toc.secnum

擴充功能也可以定義自己的警告類型。由第一方 sphinx.ext 擴充功能定義的警告類型為

autodoc
autodoc.import_object
autodoc.mocked_object
autosectionlabel.<document name>
autosummary
autosummary.import_cycle
intersphinx.external

您可以從這些類型中選擇。您也可以僅提供第一個元件來排除附加到它的所有警告。

在 1.4 版本中新增：ref.citation、ref.doc、ref.keyword、ref.numref、ref.option、ref.ref 和 ref.term。

在 1.4.2 版本中新增：app.add_directive、app.add_generic_role、app.add_node、app.add_role 和 app.add_source_parser。

在 1.5 版本中新增：misc.highlighting_failure。

在 1.5.1 版本中新增：epub.unknown_project_files。

在 1.5.2 版本中新增：toc.secnum。

在 1.6 版本中新增：ref.footnote、download.not_readable 和 image.not_readable。

在 1.7 版本中新增：ref.python。

在 2.0 版本中新增：autodoc.import_object。

在 2.1 版本中新增：autosectionlabel.<document name>。

在 3.1 版本中新增：toc.circular。

在 3.3 版本中新增：epub.duplicated_toc_entry。

在 4.3 版本中新增：toc.excluded 和 toc.not_readable。

在 4.5 版本中新增：i18n.inconsistent_references。

在 7.1 版本中新增：index。

在 7.3 版本中新增：config.cache、intersphinx.external 和 toc.no_title。

在 7.4 版本中新增：docutils 和 autosummary.import_cycle。

在 8.0 版本中新增：misc.copy_overwrite。

在 8.2 版本中新增：autodoc.mocked_object、duplicate_declaration.c、duplicate_declaration.cpp、i18n.babel、i18n.not_readable、i18n.not_writeable、ref.any、toc.duplicate_entry、toc.empty_glob 和 toc.not_included。

建構器選項¶

HTML 輸出選項¶

這些選項會影響 HTML 輸出。許多其他建構器都衍生自 HTML 輸出，並且也使用這些選項。

html_theme¶

類型:: 字串
預設:: 'alabaster'

HTML 輸出的主題。請參閱 HTML 主題設定章節。

版本 0.6 新增。

在 1.3 版本中變更：預設主題現在為 'alabaster'。

html_theme_options¶

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

一個選項字典，用於影響所選主題的外觀和風格。這些選項是主題特定的。在內建主題中可理解的選項已在此處說明。

版本 0.6 新增。

html_theme_path¶

類型:: list[str]
預設:: []

包含自訂主題的路徑清單，可以是子目錄或 zip 檔案。相對路徑會被視為相對於設定目錄的路徑。

版本 0.6 新增。

html_style¶

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

用於 HTML 頁面的樣式表。預設會使用所選主題提供的樣式表。具有該名稱的檔案必須存在於 Sphinx 的 static/ 路徑中，或存在於 html_static_path 中指定的自訂路徑之一。如果您只想新增或覆寫主題中的一些內容，請使用 CSS @import 來匯入主題的樣式表。

在 5.1 版本中變更：值可以是字串的可迭代物件。

html_title¶

類型:: 字串
預設:: 'project release documentation'

使用 Sphinx 自己的樣板產生的 HTML 文件的「標題」。這會附加到個別頁面的 <title> 標籤，並在導覽列中用作「最頂層」元素。

html_short_title¶

類型:: 字串
預設:: **html_title** 的值

HTML 文件的較短「標題」。這用於標頭和 HTML 說明文件中的連結。

版本 0.4 新增。

html_baseurl¶

類型:: 字串
預設:: ''

指向 HTML 文件根目錄的基本 URL。它用於指示文件位置，使用 標準連結關係。

在 1.8 版本中新增。

html_codeblock_linenos_style¶

類型:: 'inline' | 'table'
預設:: 'inline'

程式碼區塊的行號樣式。

'table': 使用 <table> 標籤顯示行號
'inline': 使用 <span> 標籤顯示行號

在 3.2 版本中新增。

在 4.0 版本中變更：預設值為 'inline'。

自 4.0 版本起已棄用。

html_context¶

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

要傳遞到樣板引擎上下文以用於所有頁面的值字典。也可以使用 sphinx-build 的 --html-define 命令列選項將單個值放入此字典中。

Added in version 0.5.

html_logo¶

類型:: 字串
預設:: ''

如果提供，則這必須是影像檔案的名稱 (路徑相對於設定目錄)，作為文件的標誌，或指向標誌影像檔案的 URL。它會放置在側邊欄的頂部；因此其寬度不應超過 200 像素。

在 0.4.1 版本中新增：影像檔案將複製到 _static 目錄，但前提是該檔案尚未存在於該目錄中。

在 4.0 版本中變更：也接受 URL。

html_favicon¶

類型:: 字串
預設:: ''

如果提供，則這必須是影像檔案的名稱 (路徑相對於設定目錄)，作為文件的 favicon，或指向 favicon 影像檔案的 URL。瀏覽器會將其用作標籤、視窗和書籤的圖示。它應該是 PNG、SVG、GIF 或 ICO 檔案格式的 16x16 像素圖示。

範例

html_favicon = 'static/favicon.png'

在 0.4 版本中新增：影像檔案將複製到 _static，但前提是該檔案尚未存在於該目錄中。

在 4.0 版本中變更：也接受 favicon 的 URL。

html_css_files¶

類型:: Sequence[str | tuple[str, dict[str, str]]]
預設:: []

CSS 檔案清單。條目必須是 *filename* 字串，或包含 *filename* 字串和 *attributes* 字典的元組。*filename* 必須相對於 html_static_path，或具有類似 'https://example.org/style.css' 方案的完整 URI。*attributes* 字典用於 <link> 標籤的屬性。

範例

html_css_files = [
    'custom.css',
    'https://example.com/css/custom.css',
    ('print.css', {'media': 'print'}),
]

特殊屬性 *priority* 可以設定為整數，以便在較早或較晚的步驟載入 CSS 檔案。如需更多資訊，請參閱 Sphinx.add_css_file()。

在 1.8 版本中新增。

在 3.5 版本中變更：支援 *priority* 屬性

html_js_files¶

類型:: Sequence[str | tuple[str, dict[str, str]]]
預設:: []

JavaScript 檔案清單。條目必須是 *filename* 字串，或包含 *filename* 字串和 *attributes* 字典的元組。*filename* 必須相對於 html_static_path，或具有類似 'https://example.org/script.js' 方案的完整 URI。*attributes* 字典用於 <script> 標籤的屬性。

範例

html_js_files = [
    'script.js',
    'https://example.com/scripts/custom.js',
    ('custom.js', {'async': 'async'}),
]

作為特殊屬性，*priority* 可以設定為整數，以便在較早或較晚的步驟載入 JavaScript 檔案。如需更多資訊，請參閱 Sphinx.add_js_file()。

在 1.8 版本中新增。

在 3.5 版本中變更：支援 *priority* 屬性

html_static_path¶

類型:: list[str]
預設:: []

包含自訂靜態檔案 (例如樣式表或腳本檔案) 的路徑清單。相對路徑會被視為相對於設定目錄的路徑。它們會在主題的靜態檔案之後複製到輸出的 _static 目錄，因此名為 default.css 的檔案將會覆寫主題的 default.css。

由於這些檔案並非旨在建置，因此會自動從原始檔中排除。

注意

基於安全考量，將不會複製 html_static_path 下的點檔案。如果您想有意複製它們，請將每個檔案明確新增至此設定

html_static_path = ['_static', '_static/.htaccess']

另一種方法是使用 html_extra_path，它允許複製目錄下的點檔案。

在 0.4 版本變更: html_static_path 中的路徑現在可以包含子目錄。

在 1.0 版本變更: html_static_path 中的項目現在可以是單個檔案。

在 1.8 版本變更: html_static_path 下的檔案已從來源檔案中排除。

html_extra_path¶

類型:: list[str]
預設:: []

一個路徑列表，其中包含與文件沒有直接關係的額外檔案，例如 robots.txt 或 .htaccess。相對路徑是相對於設定目錄。它們會被複製到輸出目錄。它們將覆蓋任何同名的現有檔案。

由於這些檔案並非旨在建置，因此會自動從原始檔中排除。

在 1.2 版本加入。

在 1.4 版本變更: 額外目錄中的點檔案將被複製到輸出目錄。並且在複製額外檔案和目錄時，它會參考 exclude_patterns，如果路徑與模式匹配則會忽略。

html_last_updated_fmt¶

類型:: 字串
預設:: None

如果設定，則使用給定的 strftime() 格式，將「最後更新於：」時間戳記插入到頁面頁尾。空字串等同於 '%b %d, %Y' (或與地區設定相等的格式)。

html_last_updated_use_utc¶

類型:: bool
預設:: False

對於提供給 html_last_updated_fmt 的時間，使用 GMT/UTC (+00:00) 而不是系統的本地時區。當使用的格式包含時間時，這最有用。

html_permalinks¶

類型:: bool
預設:: True

為每個標題和描述環境新增連結錨點。

在 3.5 版本加入。

html_permalinks_icon¶

類型:: 字串
預設:: '¶' (段落符號)

每個標題和描述環境的連結錨點文字。允許 HTML 實體和 Unicode。

在 3.5 版本加入。

html_sidebars¶

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

一個字典，定義自訂側邊欄範本，將文件名稱對應到範本名稱。

鍵可以包含 glob 樣式模式，在這種情況下，所有匹配的文件都將獲得指定的側邊欄。（當多個 glob 樣式模式匹配到任何文件時，會發出警告。）

每個值都必須是字串列表，其中指定要包含的完整側邊欄範本列表。如果所有或部分預設側邊欄要被包含，它們也必須放入此列表中。

預設側邊欄（對於不匹配任何模式的文件）由主題本身定義。內建主題預設使用這些範本：'localtoc.html'、'relations.html'、'sourcelink.html' 和 'searchbox.html'。

可以呈現的捆綁的第一方側邊欄範本是

localtoc.html – 當前文件的細粒度目錄
globaltoc.html – 整個文件集的粗粒度目錄，已摺疊
relations.html – 指向前一個和下一個文件的兩個連結
sourcelink.html – 如果在 html_show_sourcelink 中啟用，則是指向當前文件來源的連結
searchbox.html – 「快速搜尋」框

範例

html_sidebars = {
   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
   'using/windows': ['windows-sidebar.html', 'searchbox.html'],
}

這將在給定文件的側邊欄中呈現自訂範本 windows-sidebar.html 和快速搜尋框，並為所有其他頁面呈現預設側邊欄（除了本地 TOC 被全域 TOC 取代）。

請注意，如果選擇的主題沒有側邊欄，例如內建的 scrolls 和 haiku 主題，則此值無效。

在 1.0 版本加入: 使用 glob 鍵和指定多個側邊欄的功能。

在 1.7 版本中已棄用: html_sidebars 的單個字串值將被移除。

在 2.0 版本變更: html_sidebars 必須是字串列表，不再接受單個字串值。

html_additional_pages¶

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

應呈現為 HTML 頁面的其他範本，必須是一個字典，將文件名稱對應到範本名稱。

範例

html_additional_pages = {
    'download': 'custom-download.html.jinja',
}

這會將範本 custom-download.html.jinja 呈現為頁面 download.html。

html_domain_indices¶

類型:: bool | Sequence[str]
預設:: True

如果為 True，則除了通用索引之外，還會產生特定於網域的索引。例如，對於 Python 網域，這是全域模組索引。

此值可以是布林值或應產生的索引名稱列表。要找出特定索引的索引名稱，請查看 HTML 檔案名稱。例如，Python 模組索引的名稱為 'py-modindex'。

範例

html_domain_indices = {
    'py-modindex',
}

Added in version 1.0.

版本 7.4 更新: 允許並偏好 set 類型。

html_use_index¶

類型:: bool
預設:: True

控制是否將索引新增到 HTML 文件中。

版本 0.4 新增。

html_split_index¶

類型:: bool
預設:: False

產生兩個版本的索引：一個是包含所有條目的單頁，另一個是每個起始字母一頁。

版本 0.4 新增。

html_copy_source¶

類型:: bool
預設:: True

如果為 True，則 reStructuredText 來源會包含在 HTML 建置中，作為 _sources/docname。

html_show_sourcelink¶

類型:: bool
預設:: True

如果為 True（且 html_copy_source 也為 true），則指向 reStructuredText 來源的連結將新增到側邊欄。

版本 0.6 新增。

html_sourcelink_suffix¶

類型:: 字串
預設:: '.txt'

要附加到來源連結的後綴 (請參閱 html_show_sourcelink)，除非它們的檔案已具有此後綴。

Added in version 1.5.

html_use_opensearch¶

類型:: 字串
預設:: ''

如果為非空值，將輸出 OpenSearch 描述檔案，並且所有頁面都將包含一個指向它的 <link> 標籤。由於 OpenSearch 不支援其搜尋頁面位置的相對 URL，因此此選項的值必須是提供這些文件的基本 URL（不帶尾部斜線），例如 'https://docs.python.org'。

在 0.2 版本加入。

html_file_suffix¶

類型:: 字串
預設:: '.html'

產生的 HTML 檔案的檔案名稱後綴（副檔名）。

版本 0.4 新增。

html_link_suffix¶

類型:: 字串
預設:: html_file_suffix 的值

產生的 HTML 檔案連結的後綴。旨在支援更深奧的伺服器設定。

版本 0.6 新增。

html_show_copyright¶

類型:: bool
預設:: True

Added in version 1.0.

html_show_search_summary¶

類型:: bool
預設:: True

顯示搜尋結果的摘要，即關鍵字周圍的文字。

在 4.5 版本加入。

html_show_sphinx¶

類型:: bool
預設:: True

將「使用 Sphinx 建立」新增到 HTML 頁尾。

版本 0.4 新增。

html_output_encoding¶

類型:: 字串
預設:: 'utf-8'

HTML 輸出檔案的編碼。此編碼名稱必須是有效的 Python 編碼名稱和有效的 HTML charset 值。

Added in version 1.0.

html_compact_lists¶

類型:: bool
預設:: True

如果為 True，則所有項目都由單個段落和/或所有項目等的子列表組成的列表…（遞迴定義）將不會為其任何項目使用 <p> 元素。這是標準的 docutils 行為。預設值：True。

Added in version 1.0.

html_secnumber_suffix¶

類型:: 字串
預設:: '. '

HTML 輸出中章節編號的後綴。設定為 ' ' 以抑制章節編號上的最終點。

Added in version 1.0.

html_search_language¶

類型:: 字串
預設:: language 的值

用於產生 HTML 全文檢索索引的語言。預設為使用 language 選擇的全域語言。如果此語言不受支援，則使用英語 ('en') 作為後備選項。

支援以下語言

da – 丹麥文
nl – 荷蘭文
en – 英語
fi – 芬蘭文
fr – 法文
de – 德文
hu – 匈牙利文
it – 義大利文
ja – 日文
no – 挪威語
pt – 葡萄牙文
ro – 羅馬尼亞文
ru – 俄文
es – 西班牙文
sv – 瑞典文
tr – 土耳其文
zh – 中文

提示

加速建置速度

每種語言（日語除外）都提供自己的詞幹提取演算法。Sphinx 預設使用 Python 實作。如果您想加速建置索引檔案，可以使用第三方套件 (PyStemmer) 執行 pip install PyStemmer。

在 1.1 版本加入: 支援英語 (en) 和日語 (ja)。

在 1.3 版本變更: 加入其他語言。

html_search_options¶

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

一個字典，其中包含搜尋語言支援的選項。這些選項的含義取決於選擇的語言。目前，只有日語和中文支援選項。

日語:

type – 要使用的分詞器類型。

其他選項取決於使用的分詞器。

'sphinx.search.ja.DefaultSplitter': TinySegmenter 演算法，預設使用。
'sphinx.search.ja.MecabSplitter':: MeCab 綁定。要使用此分詞器，需要 'mecab' python 綁定或動態連結程式庫（Linux 的 'libmecab.so'，Windows 的 'libmecab.dll'）。
'sphinx.search.ja.JanomeSplitter':: Janome 綁定。要使用此分詞器，需要 Janome。

在 1.6 版本中已棄用: 'mecab'、'janome' 和 'default' 已棄用。為了保持相容性，'mecab'、'janome' 和 'default' 也是可接受的。

'mecab' 的選項

dic_enc:: dic_enc 選項是 MeCab 演算法的編碼。
dict:: dict 選項是要用於 MeCab 演算法的字典。
lib:: lib 選項是透過 ctypes 尋找 MeCab 程式庫的程式庫名稱（如果未安裝 Python 綁定）。

例如

html_search_options = {
    'type': 'mecab',
    'dic_enc': 'utf-8',
    'dict': '/path/to/mecab .dic',
    'lib': '/path/to/libmecab.so',
}

'janome' 的選項

user_dic:: user_dic 選項是 Janome 的使用者字典檔案路徑。
user_dic_enc:: user_dic_enc 選項是 user_dic 選項指定的使用者字典檔案的編碼。預設值為 ‘utf8’。

中文:

dict: 用於自訂字典的 jieba 字典路徑。

版本 1.1 新增。

在 1.4 版本變更: 允許日語的 type 設定中使用任何自訂分詞器。

html_search_scorer¶

類型:: 字串
預設:: ''

JavaScript 檔案的名稱（相對於設定目錄），用於實作搜尋結果評分器。如果為空，將使用預設值。

評分器必須實作以下介面，並且可以選擇性地定義 score() 函數以進行更精細的控制。

const Scorer = {
    // Implement the following function to further tweak the score for each result
    score: result => {
      const [docName, title, anchor, descr, score, filename] = result

      // ... calculate a new score ...
      return score
    },

    // query matches the full name of an object
    objNameMatch: 11,
    // or matches in the last dotted part of the object name
    objPartialMatch: 6,
    // Additive scores depending on the priority of the object
    objPrio: {
      0: 15, // used to be importantResults
      1: 5, // used to be objectResults
      2: -5, // used to be unimportantResults
    },
    //  Used when the priority is not in the mapping.
    objPrioDefault: 0,

    // query found in title
    title: 15,
    partialTitle: 7,

    // query found in terms
    term: 5,
    partialTerm: 2,
};

在 1.2 版本加入。

html_scaled_image_link¶

類型:: bool
預設:: True

將已使用縮放選項（scale、width 或 height）調整大小的圖像連結到其原始完整解析度的圖像。這不會覆蓋 image 指令上 target 選項給出的任何連結（如果存在）。

提示

要在每個圖像的基礎上停用此功能，請將 no-scaled-link 類別新增到圖像指令

.. image:: sphinx.png
   :scale: 50%
   :class: no-scaled-link

Added in version 1.3.

在 3.0 版本變更: 具有 no-scaled-link 類別的圖像將不會被連結。

html_math_renderer¶

類型:: 字串
預設:: 'mathjax'

用於 HTML 輸出的數學渲染器。捆綁的渲染器是 mathjax 和 imgmath。您還必須在 extensions 中載入相關的擴充功能。

在 1.8 版本中新增。

單一 HTML 輸出的選項¶

這些選項會影響單一 HTML 輸出。此建置器衍生自 HTML 建置器，因此 HTML 選項也適用於適當的地方。

singlehtml_sidebars¶

類型:: dict[str, Sequence[str]]
預設:: html_sidebars 的值

一個字典，定義自訂側邊欄範本，將文件名稱對應到範本名稱。

這與 html_sidebars 具有相同的效果，但唯一允許的鍵是 'index'，所有其他鍵都會被忽略。

HTML 說明輸出的選項¶

這些選項會影響 HTML 說明輸出。此建置器衍生自 HTML 建置器，因此 HTML 選項也適用於適當的地方。

htmlhelp_basename¶

類型:: 字串
預設:: '{project}doc'

HTML 說明建置器的輸出檔案基本名稱。預設值是 專案名稱，移除空格並附加 doc。

htmlhelp_file_suffix¶

類型:: 字串
預設:: '.html'

這是產生的 HTML 說明檔案的檔案名稱後綴。

在 2.0 版本加入。

htmlhelp_link_suffix¶

類型:: 字串
預設:: htmlhelp_file_suffix 的值

產生的 HTML 檔案連結的後綴。

在 2.0 版本加入。

Apple Help 輸出的選項¶

Added in version 1.3.

這些選項會影響 Apple Help 輸出。此建置器衍生自 HTML 建置器，因此 HTML 選項也適用於適當的地方。

注意

Apple Help 輸出僅適用於 Mac OS X 10.6 及更高版本，因為它需要 hiutil 和 codesign 命令列工具，這兩個工具都不是開放原始碼。

您可以使用 applehelp_disable_external_tools 停用這些工具的使用，但在索引器在套件中的 .lproj 目錄上執行之前，結果將不是有效的說明書。

applehelp_bundle_name¶

類型:: 字串
預設:: project 的值

Apple Help Book 的基本名稱。預設值是 專案名稱，移除空格。

applehelp_bundle_id¶

類型:: 字串
預設:: None

說明書套件的套件 ID。

警告

您必須設定此值才能產生 Apple Help。

applehelp_bundle_version¶

類型:: 字串
預設:: '1'

套件版本，以字串形式表示。

applehelp_dev_region¶

類型:: 字串
預設:: 'en-us'

開發區域。預設為 Apple 建議的設定 'en-us'。

applehelp_icon¶

類型:: 字串
預設:: None

說明套件圖示檔案的路徑，或 None 表示沒有圖示。根據 Apple 的文件，這應該是應用程式圖示的 16x16 像素版本，具有透明背景，並儲存為 PNG 檔案。

applehelp_kb_product¶

類型:: 字串
預設:: 'project-release'

用於 applehelp_kb_url 的產品標籤。

applehelp_kb_url¶

類型:: 字串
預設:: None

您的知識庫伺服器的 URL，例如 https://example.com/kbsearch.py?p='product'&q='query'&l='lang'。在執行時，Help Viewer 將把 'product' 替換為 applehelp_kb_product 的內容，'query' 替換為使用者在搜尋框中輸入的文字，'lang' 替換為使用者的系統語言。

將此設定為 None 以停用遠端搜尋。

applehelp_remote_url¶

類型:: 字串
預設:: None

遠端內容的 URL。您可以將 Help Book 的 Resources 目錄副本放在此位置，Help Viewer 將嘗試使用它來擷取更新的內容。

例如，如果您將其設定為 https://example.com/help/Foo/，並且 Help Viewer 想要英文使用者的 index.html 副本，它將查看 https://example.com/help/Foo/en.lproj/index.html。

將此設定為 None 表示沒有遠端內容。

applehelp_index_anchors¶

類型:: bool
預設:: False

告訴說明索引器為產生的 HTML 中的錨點建立索引。這對於使用 AHLookupAnchor 函數或程式碼中的 openHelpAnchor:inBook: 方法跳轉到特定主題很有用。它還允許您使用 help:anchor URL；請參閱 Apple 文件以取得有關此主題的更多資訊。

applehelp_min_term_length¶

類型:: 字串
預設:: None

控制說明索引器的最小詞彙長度。如果為 None，則使用預設長度。

applehelp_stopwords¶

類型:: 字串
預設:: language 的值

語言規範（以使用內建停用詞）或停用詞 plist 的路徑，或 None（如果您不想使用停用詞）。預設停用詞 plist 可以在 /usr/share/hiutil/Stopwords.plist 找到，並且在撰寫本文時，包含以下語言的停用詞

德語 (de)
英語 (en)
西班牙語 (es)
法語 (fr)
匈牙利語 (hu)
義大利語 (it)
瑞典語 (sv)

applehelp_locale¶

類型:: 字串
預設:: language 的值

指定要為其產生說明的語言環境。這用於確定 Help Book 的 Resources 內的 .lproj 目錄的名稱，並傳遞給說明索引器。

applehelp_title¶

類型:: 字串
預設:: 'project 說明'

指定說明書標題。

applehelp_codesign_identity¶

類型:: 字串
預設:: CODE_SIGN_IDENTITY 的值

指定用於程式碼簽署的身分。如果不要執行程式碼簽署，請使用 None。

預設為 CODE_SIGN_IDENTITY 環境變數的值，該變數由 Xcode 為腳本建置階段設定，如果未設定該變數，則預設為 None。

applehelp_codesign_flags¶

類型:: list[str]
預設:: OTHER_CODE_SIGN_FLAGS 的值

在簽署說明書時，要傳遞給 codesign 的其他引數列表。

預設為基於 OTHER_CODE_SIGN_FLAGS 環境變數的值的列表，該變數由 Xcode 為腳本建置階段設定，如果未設定該變數，則預設為空列表。

applehelp_codesign_path¶

類型:: 字串
預設:: '/usr/bin/codesign'

codesign 程式的路徑。

applehelp_indexer_path¶

類型:: 字串
預設:: '/usr/bin/hiutil'

指向 hiutil 程式的路徑。

applehelp_disable_external_tools¶

類型:: bool
預設:: False

無論指定何種其他設定，皆不執行索引器或程式碼簽署工具。

這主要用於測試，或是在您想於非 macOS 平台上執行 Sphinx 建置，然後基於某些原因在 Mac 上完成最後步驟的情況。

EPUB 輸出的選項¶

這些選項會影響 EPUB 輸出。此建置器衍生自 HTML 建置器，因此 HTML 選項在適用的情況下也適用。

注意

某些選項的實際值並不重要，但它們是都柏林核心 (Dublin Core) metadata 所必需的。

epub_basename¶

類型:: 字串
預設:: project 的值

EPUB 檔案的基本名稱。

epub_theme¶

類型:: 字串
預設:: 'epub'

EPUB 輸出的 HTML 主題。由於預設主題未針對小螢幕空間進行最佳化，因此對 HTML 和 EPUB 輸出使用相同的主題通常不明智。此選項預設為 'epub'，此主題旨在節省視覺空間。

epub_theme_options¶

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

一個選項字典，用於影響所選主題的外觀和風格。這些選項是主題特定的。在內建主題中可理解的選項已在此處說明。

在 1.2 版本加入。

epub_title¶

類型:: 字串
預設:: project 的值

文件的標題。

在版本 2.0 中變更：預設為 project 選項（先前為 html_title）。

epub_description¶

類型:: 字串
預設:: 'unknown'

文件的描述。

版本 1.4 新增。

在版本 1.5 中變更：從 epub3_description 重新命名

epub_author¶

類型:: 字串
預設:: author 的值

文件的作者。這會放入都柏林核心 (Dublin Core) metadata 中。

epub_contributor¶

類型:: 字串
預設:: 'unknown'

在 EPUB 出版品的內容建立中扮演次要角色的人員、組織等的名稱。

版本 1.4 新增。

在版本 1.5 中變更：從 epub3_contributor 重新命名

epub_language¶

類型:: 字串
預設:: language 的值

文件的語言。這會放入都柏林核心 (Dublin Core) metadata 中。

epub_publisher¶

類型:: 字串
預設:: author 的值

文件的發行者。這會放入都柏林核心 (Dublin Core) metadata 中。您可以使用任何合理的字串，例如專案首頁。

epub_copyright¶

類型:: 字串
預設:: copyright 的值

文件的著作權。如需允許的格式，請參閱 copyright。

epub_identifier¶

類型:: 字串
預設:: 'unknown'

文件的識別碼。這會放入都柏林核心 (Dublin Core) metadata 中。對於已出版的文件，這是 ISBN 號碼，但您也可以使用替代方案，例如專案首頁。

epub_scheme¶

類型:: 字串
預設:: 'unknown'

用於 epub_identifier 的出版方案。這會放入都柏林核心 (Dublin Core) metadata 中。對於已出版的書籍，方案為 'ISBN'。如果您使用專案首頁，'URL' 似乎是合理的。

epub_uid¶

類型:: 字串
預設:: 'unknown'

文件的唯一識別碼。這會放入都柏林核心 (Dublin Core) metadata 中。您可以使用 XML 的名稱格式字串。您不能使用連字號、句點、數字作為第一個字元。

epub_cover¶

類型:: tuple[str, str]
預設:: ()

封面頁資訊。這是一個元組，其中包含封面圖片和 html 範本的檔名。呈現的 html 封面頁會作為 spine 中的第一個項目插入 content.opf 中。如果範本檔名為空，則不會建立 html 封面頁。如果元組為空，則完全不會建立封面。

範例

epub_cover = ('_static/cover.png', 'epub-cover.html')
epub_cover = ('_static/cover.png', '')
epub_cover = ()

版本 1.1 新增。

epub_css_files¶

類型:: Sequence[str | tuple[str, dict[str, str]]]
預設:: []

CSS 檔案的清單。項目必須是檔名字串，或包含檔名字串和屬性字典的元組。檔名必須相對於 html_static_path，或具有 scheme 的完整 URI，例如 'https://example.org/style.css'。屬性字典用於 <link> 標籤的屬性。如需更多資訊，請參閱 html_css_files。

在 1.8 版本中新增。

epub_guide¶

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

content.opf 的 guide 元素的 metadata。這是一個元組序列，其中包含選用 guide 資訊的類型、uri 和標題。如需詳細資訊，請參閱 OPF 文件。如果可能，會自動插入 cover 和 toc 類型的預設項目。但是，如果預設項目不適合，則可以明確覆寫這些類型。

範例

epub_guide = (
    ('cover', 'cover.html', 'Cover Page'),
)

預設值為 ()。

epub_pre_files¶

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

應在 Sphinx 產生的文字之前插入的其他檔案。它是一個元組清單，其中包含檔名和標題。如果標題為空，則不會將項目新增至 toc.ncx。

範例

epub_pre_files = [
    ('index.html', 'Welcome'),
]

epub_post_files¶

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

應在 Sphinx 產生的文字之後插入的其他檔案。它是一個元組清單，其中包含檔名和標題。此選項可用於新增附錄。如果標題為空，則不會將項目新增至 toc.ncx。

範例

epub_post_files = [
    ('appendix.xhtml', 'Appendix'),
]

epub_exclude_files¶

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

在建置目錄中產生/複製，但不應包含在 EPUB 檔案中的檔案序列。

epub_tocdepth¶

類型:: int
預設:: 3

toc.ncx 檔案中目錄的深度。它應該是個大於零的整數。

提示

深度巢狀的目錄可能難以瀏覽。

epub_tocdup¶

類型:: bool
預設:: True

此旗標決定是否在其巢狀目錄清單的開頭再次插入 ToC 項目。這樣可以更輕鬆地導航到章節的頂部，但可能會造成混淆，因為它會在一個清單中混合不同深度的項目。

epub_tocscope¶

類型:: 'default' | 'includehidden'
預設:: 'default'

此設定控制 EPUB 目錄的範圍。此設定可以具有以下值

'default': 包含所有未隱藏的 ToC 項目
'includehidden': 包含所有 ToC 項目

在 1.2 版本加入。

epub_fix_images¶

類型:: bool
預設:: False

嘗試修正某些 EPUB 閱讀器不支援的圖片格式。目前，具有小調色盤的 palette 圖片會被升級。預設情況下會停用此功能，因為自動轉換可能會遺失資訊。您需要安裝 Python 圖片庫 (Pillow) 才能使用此選項。

在 1.2 版本加入。

epub_max_image_width¶

類型:: int
預設:: 0

此選項指定圖片的最大寬度。如果將其設定為大於零的值，則會相應地縮放寬度大於給定值的圖片。如果為零，則不執行縮放。您需要安裝 Python 圖片庫 (Pillow) 才能使用此選項。

在 1.2 版本加入。

epub_show_urls¶

類型:: 'footnote' | 'no' | 'inline'
預設:: 'footnote'

控制如何顯示 URL 位址。對於沒有其他方式可以顯示連結 URL 的閱讀器來說，這非常有用。此設定可以具有以下值

'inline': 以括號內嵌顯示 URL。
'footnote': 在註腳中顯示 URL。
'no': 不顯示 URL。

可以透過為 link-target 類別新增 CSS 規則來自訂內嵌 URL 的顯示方式。

在 1.2 版本加入。

epub_use_index¶

類型:: bool
預設:: html_use_index 的值

將索引新增至 EPUB 文件。

在 1.2 版本加入。

epub_writing_mode¶

類型:: 'horizontal' | 'vertical'
預設:: 'horizontal'

它指定書寫方向。它可以接受 'horizontal' 和 'vertical'

`epub_writing_mode`	`'horizontal'`	`'vertical'`
writing-mode (書寫模式)	`horizontal-tb (水平由上至下)`	`vertical-rl (垂直由右至左)`
page progression (頁面進程)	left to right (由左至右)	right to left (由右至左)
iBook 的捲動主題支援	scroll-axis is vertical. (捲動軸為垂直)	scroll-axis is horizontal. (捲動軸為水平)

LaTeX 輸出的選項¶

這些選項會影響 LaTeX 輸出。

latex_engine¶

類型:: 'pdflatex' | 'xelatex' | 'lualatex' | 'platex' | 'uplatex'
預設:: 'pdflatex'

用於建置文件的 LaTeX 引擎。此設定可以具有以下值

'pdflatex' – PDFLaTeX (預設)
'xelatex' – XeLaTeX (如果 language 是 el、zh_CN 或 zh_TW 其中之一，則為預設值)
'lualatex' – LuaLaTeX
'platex' – pLaTeX
'uplatex' – upLaTeX (如果 language 是 'ja'，則為預設值)

重要事項

'pdflatex' 對於 Unicode 字元的支援有限。如果您的專案使用 Unicode 字元，則將引擎設定為 'xelatex' 或 'lualatex'，並確保使用字形涵蓋範圍足夠廣泛的 OpenType 字型，通常比嘗試讓 'pdflatex' 處理額外的 Unicode 字元更容易。自 Sphinx 2.0 起，預設字型為 GNU FreeFont，它對拉丁文、西里爾文和希臘文字形具有良好的涵蓋範圍。

注意

Sphinx 2.0 新增了對使用拉丁語和 'pdflatex' 的文件中偶爾出現的西里爾文和希臘字母或單字的支援。若要啟用此功能，必須適當地使用 latex_elements 的 'fontenc' 鍵。

注意

與 HTML 輸出中的 MathJaX 數學渲染相反，LaTeX 需要一些額外的設定來支援 math 中的 Unicode 文字：據我們所知，唯一的全面解決方案是使用 'xelatex' 或 'lualatex'並新增 r'\usepackage{unicode-math}' (例如，透過 latex_elements 的 'preamble' 鍵)。您可能偏好 r'\usepackage[math-style=literal]{unicode-math}' 以將 Unicode 文字 (例如 α (U+03B1)) 保留在輸出中，而不是渲染為 $\alpha$。

在版本 2.1.0 中變更：對於中文文件，預設使用 'xelatex' (和 LaTeX 套件 xeCJK)。

在版本 2.2.1 中變更：對於希臘文文件，預設使用 'xelatex'。

在版本 2.3 中變更：新增 'uplatex' 支援。

在版本 4.0 中變更：對於日文文件，預設使用 'uplatex'。

latex_documents¶

類型:: Sequence[tuple[str, str, str, str, str, bool]]
預設:: 預設的 LaTeX 文件

此值決定如何將文件樹狀結構分組到 LaTeX 原始檔中。它必須是元組 (startdocname, targetname, title, author, theme, toctree_only) 的清單，其中項目為

startdocname: 字串，指定 LaTeX 檔案主文件的文件名稱。ToC 樹狀結構中 startdoc 文件引用的所有文件都將包含在 LaTeX 檔案中。(如果您想將預設主文件用於 LaTeX 建置，請在此處提供您的 master_doc。)
targetname: 輸出目錄中 LaTeX 檔案的檔名。
title: LaTeX 文件標題。可以為空以使用 startdoc 文件的標題。這會作為 LaTeX 標記插入，因此反斜線或 & 符號等特殊字元必須以適當的 LaTeX 命令表示，才能按字面插入。
作者: LaTeX 文件的作者。與標題相同的 LaTeX 標記注意事項適用。使用 \\and 分隔多位作者，例如：'John \\and Sarah' (反斜線必須經過 Python 逸出才能到達 LaTeX)。
theme: LaTeX 主題。請參閱 latex_theme。
toctree_only: 必須為 True 或 False。如果為 True，則 startdoc 文件本身不會包含在輸出中，僅包含它透過 ToC 樹狀結構引用的文件。使用此選項，您可以在主文件中放入額外內容，這些內容會顯示在 HTML 中，但不會顯示在 LaTeX 輸出中。

在版本 0.3 中新增：第 6 個項目 toctree_only。仍然接受具有 5 個項目的元組。

在版本 1.2 中新增：過去，包含您自己的文件類別需要您在文件類別名稱前面加上字串 “sphinx”。現在已不再需要這樣做。

latex_logo¶

類型:: 字串
預設:: ''

如果給定，則這必須是圖片檔案的名稱 (路徑相對於設定目錄)，它是文件的標誌。它放置在標題頁的頂部。

latex_toplevel_sectioning¶

類型:: 'part' | 'chapter' | 'section'
預設:: None

此值決定最頂層的分節單位。如果 latex_theme 為 'howto'，則預設設定為 'section'；如果為 'manual'，則預設設定為 'chapter'。在這兩種情況下的替代方案是指定 'part'，這表示 LaTeX 文件將使用 \part 命令。

在這種情況下，深一層分節單位的編號會與 HTML 編號不同步，因為預設情況下，LaTeX 在遇到 \part 命令時不會重設 \chapter 編號 (或 'howto' 主題的 \section)。

版本 1.4 新增。

latex_appendices¶

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

要作為附錄附加到所有手冊的文件名稱清單。如果 latex_theme 設定為 'howto'，則會忽略此選項。

latex_domain_indices¶

類型:: bool | Sequence[str]
預設:: True

如果為 True，則除了通用索引之外，還會產生特定於網域的索引。例如，對於 Python 網域，這是全域模組索引。

此值可以是布林值或應產生的索引名稱列表。要找出特定索引的索引名稱，請查看 HTML 檔案名稱。例如，Python 模組索引的名稱為 'py-modindex'。

範例

latex_domain_indices = {
    'py-modindex',
}

Added in version 1.0.

版本 7.4 更新: 允許並偏好 set 類型。

latex_show_pagerefs¶

類型:: bool
預設:: False

在內部參照後新增頁碼參照。這對於手冊的列印副本非常有用。

Added in version 1.0.

latex_show_urls¶

類型:: 'no' | 'footnote' | 'inline'
預設:: 'no'

控制如何顯示 URL 位址。這對於手冊的列印副本非常有用。此設定可以具有以下值

'no': 不顯示 URL
'footnote': 在註腳中顯示 URL
'inline': 以括號內嵌顯示 URL

Added in version 1.0.

在版本 1.1 中變更：此值現在是字串；先前它是布林值，而 true 值選擇了 'inline' 顯示。為了向後相容性，仍然接受 True。

latex_use_latex_multicolumn¶

類型:: bool
預設:: False

在表格中合併的儲存格使用標準 LaTeX 的 \multicolumn。

False: Sphinx 自己的巨集用於網格表格中合併的儲存格。它們允許一般內容 (文字區塊、清單、引言區塊等)，但如果使用 tabularcolumns 指令來注入類型為 >{..}、<{..}、@{..} 的 LaTeX 標記作為欄規格，則可能會出現問題。
True: 使用 LaTeX 的標準 \multicolumn；這與水平合併儲存格中的文字區塊不相容，如果表格是使用 tabulary 渲染的，也與此類儲存格中的多個段落不相容。

在版本 1.6 中新增。

latex_table_style¶

類型:: list[str]
預設:: ['booktabs', 'colorrows']

樣式類別 (字串) 的清單。目前支援

'booktabs': 沒有垂直線，只有 2 或 3 條水平線 (後者在有標頭的情況下)，使用 booktabs 套件。
'borderless': 完全沒有線條。
'colorrows': 表格列以交替的背景顏色渲染。自訂它們的介面是透過 The sphinxsetup configuration setting 的專用鍵。

重要事項

使用 'colorrows' 樣式時，\rowcolors LaTeX 命令會變成 no-op (此命令有其限制，並且從未正確支援 Sphinx 在 LaTeX 中產生的所有表格類型)。請更新您的專案以改用 latex 表格顏色組態鍵。

若要自訂表格的樣式，如果表格是使用指令定義的，請使用 :class: 選項，否則在表格之前插入 rst-class 指令 (參見表格)。

目前可辨識的類別為 booktabs、borderless、standard、colorrows、nocolorrows。後兩者可以與前三者中的任何一個組合使用。standard 類別會產生具有水平線和垂直線的表格 (到目前為止，這是 Sphinx 的預設設定)。

如果設定了單列多欄合併儲存格的列顏色，則它將遵守列顏色。另請參閱 The sphinxsetup configuration setting 區段中的 TableMergeColor{Header,Odd,Even}。

注意

在 LaTeX 中硬式編碼，即使透過欄規格中的 \columncolor 設定了欄顏色 (請參閱 tabularcolumns)，單個儲存格仍將遵守列顏色。Sphinx 提供了 \sphinxnorowcolor，可用於表格欄規格中，如下所示
```
>{\columncolor{blue}\sphinxnorowcolor}
```
Sphinx 還提供了 \sphinxcolorblend，但這需要 xcolor 套件。以下是一個範例
```
>{\sphinxcolorblend{!95!red}}
```
這表示在此欄中，列的顏色會稍微帶有紅色色調；有關其 \blendcolors 命令的語法詳情，請參閱 xcolor 文件（使用 \blendcolors 取代 \sphinxcolorblend 會修改儲存格內容的顏色，而不是儲存格背景顏色面板的顏色…）。您可以在本文件的已棄用的 API 章節的 PDF 格式範例中找到用法。

提示

如果您想為給定欄的儲存格內容使用特殊顏色，請使用 >{\noindent\color{<color>}}，可能還需加上上述的設定。
多列合併儲存格，無論是單欄還是多欄，目前都會忽略任何設定的欄、列或儲存格顏色。
簡單儲存格可以透過 raw 指令以及在儲存格內容中任何位置使用的 \cellcolor LaTeX 命令來設定自訂顏色。目前這在合併儲存格中無效，無論其類型為何。

提示

在未全域使用 'booktabs' 的文件中，可以透過 booktabs 類別來設定個別表格的樣式，但必須將 r'\usepackage{booktabs}' 新增至 LaTeX 前言。

另一方面，對於沒有額外套件的個別表格，可以使用 colorrows 類別（因為 Sphinx 從 5.3.0 版本開始總是載入 colortbl）。

在 5.3.0 版本中新增。

在 6.0.0 版本中變更：修改預設值從 [] 變更為 ['booktabs', 'colorrows']。

latex_use_xindy¶

類型:: bool
預設:: True if latex_engine in {'xelatex', 'lualatex'} else False

使用 Xindy 來準備一般詞彙的索引。預設情況下，LaTeX 建置器使用 makeindex 來準備一般詞彙的索引。使用 Xindy 表示具有 UTF-8 字元的單字將會針對 language 正確排序。

如果 latex_engine 是 'platex'（日文文件；屆時 mendex 會取代 makeindex），則會忽略此選項。
對於 'xelatex' 或 'lualatex'，預設值為 True，因為如果任何索引詞彙以非 ASCII 字元開頭，makeindex 會建立包含 UTF-8 編碼的無效位元組的 .ind 檔案。使用 'lualatex' 時，這會導致 PDF 建置失敗。
對於 'pdflatex'，預設值為 False，但建議非英文文件盡快使用 True，因為某些索引詞彙使用語言腳本中的非 ASCII 字元。如果 latex_use_xindy 保留為預設值 False，則嘗試索引第一個字元為非 ASCII 字元的詞彙將會導致建置失敗。

Sphinx 為 xindy 基本發行版新增了一些專用支援，以便將 'pdflatex' 引擎與西里爾字母腳本搭配使用。使用 'pdflatex' 和 Unicode 引擎，西里爾字母文件可以正確處理拉丁名稱的索引，即使是帶有變音符號的名稱也沒問題。

在 1.8 版本中新增。

latex_elements¶

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

Added in version 0.5.

請參閱 latex_elements 的完整文件.

latex_docclass¶

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

一個字典，將 'howto' 和 'manual' 對應到將用作兩個 Sphinx 類別基礎的真實文件類別名稱。預設值是針對 'howto' 使用 'article'，針對 'manual' 使用 'report'。

Added in version 1.0.

在 1.5 版本中變更：在日文文件中（language 是 'ja'），預設情況下，針對 'howto' 使用 'jreport'，針對 'manual' 使用 'jsbook'。

latex_additional_files¶

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

相對於設定目錄的檔案名稱清單，在建置 LaTeX 輸出時複製到建置目錄。這對於複製 Sphinx 不會自動複製的檔案，或使用自訂版本覆寫 Sphinx LaTeX 支援檔案很有用。來源檔案中參考的影像檔案（例如透過 .. image::）會自動複製，不應在此處列出。

注意

副檔名為 .tex 的檔案將會自動移交給由 sphinx-build -M latexpdf 或 make latexpdf 觸發的 PDF 建置程序。如果新增檔案只是為了從修改過的前言中 \input{}，您必須新增進一步的後綴，例如 .txt 到檔案名稱，並相應地調整 \input{} 巨集。

版本 0.6 新增。

在 1.2 版本中變更：這會覆寫 Sphinx 提供的檔案，例如 sphinx.sty。

latex_theme¶

類型:: 字串
預設:: 'manual'

LaTeX 輸出應使用的「主題」。它是 LaTeX 輸出的設定集合（例如文件類別、頂層分節單位等等）。

捆綁的第一方 LaTeX 主題為 manual 和 howto

manual: 用於撰寫手冊的 LaTeX 主題。它匯入 report 文件類別（日文文件使用 jsbook）。
howto: 用於撰寫文章的 LaTeX 主題。它匯入 article 文件類別（日文文件使用 jreport）。latex_appendices 僅適用於此主題。

在 3.0 版本中新增。

latex_theme_options¶

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

影響所選主題外觀和風格的選項字典。這些是主題特定的。

在 3.1 版本中新增。

latex_theme_path¶

類型:: list[str]
預設:: []

包含自訂 LaTeX 主題作為子目錄的路徑清單。相對路徑被視為相對於設定目錄。

在 3.0 版本中新增。

文字輸出選項¶

這些選項會影響文字輸出。

text_add_secnumbers¶

類型:: bool
預設:: True

在文字輸出中包含章節編號。

Added in version 1.7.

text_newlines¶

類型:: 'unix' | 'windows' | 'native'
預設:: 'unix'

決定文字輸出中使用的行尾字元。

'unix': 使用 Unix 樣式的行尾符號 (\n)。
'windows': 使用 Windows 樣式的行尾符號 (\r\n)。
'native': 使用建置文件平台上的行尾符號樣式。

版本 1.1 新增。

text_secnumber_suffix¶

類型:: 字串
預設:: '. '

文字輸出中章節編號的後綴。設定為 ' ' 以隱藏章節編號上的句點。

Added in version 1.7.

text_sectionchars¶

類型:: 字串
預設:: '*=-~"+`'

一個包含 7 個字元的字串，應用於底線標示章節。第一個字元用於第一層標題，第二個字元用於第二層標題，依此類推。

版本 1.1 新增。

手冊頁面輸出選項¶

這些選項會影響手冊頁面輸出。

man_pages¶

類型:: Sequence[tuple[str, str, str, str, str]]
預設:: 預設手冊頁面

此值決定如何將文件樹狀結構分組到手冊頁面中。它必須是元組 (startdocname, name, description, authors, section) 的清單，其中項目為

startdocname: 字串，指定手冊頁面主文件的文件名稱。ToC 樹狀結構中 startdoc 文件參考的所有文件都將包含在手冊頁面中。（如果您想對手冊頁面建置使用預設主文件，請在此處提供您的 master_doc。）
name: 手冊頁面的名稱。這應該是一個簡短的字串，不包含空格或特殊字元。它用於決定檔案名稱以及手冊頁面的名稱（在 NAME 章節中）。
description: 手冊頁面的描述。這用於 NAME 章節中。如果您不想自動產生 NAME 章節，則可以為空字串。
authors: 作者字串清單，或單一字串。如果您不想自動產生手冊頁面中的 AUTHORS 章節，則可以為空字串或清單。
區段: 手冊頁面章節。用於輸出檔案名稱以及手冊頁面標頭中。

Added in version 1.0.

man_show_urls¶

類型:: bool
預設:: False

在連結後新增 URL 位址。

版本 1.1 新增。

man_make_section_directory¶

類型:: bool
預設:: True

在建置手冊頁面時建立章節目錄。

在 3.3 版本中新增。

在 4.0 版本中變更：預設值現在為 False（先前為 True）。

在 4.0.2 版本中變更：還原預設值中的變更。

Texinfo 輸出選項¶

這些選項會影響 Texinfo 輸出。

texinfo_documents¶

類型:: Sequence[tuple[str, str, str, str, str, str, str, bool]]
預設:: 預設 Texinfo 文件

此值決定如何將文件樹狀結構分組到 Texinfo 原始檔中。它必須是元組 (startdocname, targetname, title, author, dir_entry, description, category, toctree_only) 的清單，其中項目為

startdocname: 字串，指定 Texinfo 檔案主文件的文件名稱。ToC 樹狀結構中 startdoc 文件參考的所有文件都將包含在 Texinfo 檔案中。（如果您想對 Texinfo 建置使用預設主文件，請在此處提供您的 master_doc。）
targetname: 輸出目錄中 Texinfo 檔案的檔案名稱（不含副檔名）。
title: Texinfo 文件標題。可以為空，以使用 startdoc 文件的標題。以 Texinfo 標記插入，因此像 @ 和 {} 之類的特殊字元將需要逸出才能按字面插入。
作者: Texinfo 文件的作者。以 Texinfo 標記插入。使用 @* 分隔多位作者，如：'John@*Sarah'。
dir_entry: 將顯示在頂層 DIR 選單檔案中的名稱。
description: 將顯示在頂層 DIR 選單檔案中的描述性文字。
category: 指定此項目將顯示在頂層 DIR 選單檔案中的章節。
toctree_only: 必須為 True 或 False。如果為 True，則 startdoc 文件本身不會包含在輸出中，只會包含由 ToC 樹狀結構參考的文件。使用此選項，您可以將額外內容放入主文件中，這些內容會顯示在 HTML 中，但不會顯示在 Texinfo 輸出中。

版本 1.1 新增。

texinfo_appendices¶

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

要作為附錄附加到所有手冊的文件名稱清單。

版本 1.1 新增。

texinfo_cross_references¶

類型:: bool
預設:: True

在文件中產生內嵌參考。停用內嵌參考可以使 info 檔案在使用獨立閱讀器 (info) 時更具可讀性。

在 4.4 版本中新增。

texinfo_domain_indices¶

類型:: bool | Sequence[str]
預設:: True

如果為 True，則除了通用索引之外，還會產生特定於網域的索引。例如，對於 Python 網域，這是全域模組索引。

此值可以是布林值或應產生的索引名稱列表。要找出特定索引的索引名稱，請查看 HTML 檔案名稱。例如，Python 模組索引的名稱為 'py-modindex'。

範例

texinfo_domain_indices = {
    'py-modindex',
}

版本 1.1 新增。

版本 7.4 更新: 允許並偏好 set 類型。

texinfo_elements¶

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

一個字典，其中包含 Texinfo 片段，這些片段會覆寫 Sphinx 通常放入產生的 .texi 檔案中的片段。

您可能想要覆寫的鍵包括

'paragraphindent'
每個段落第一行要縮排的空格數，預設值為 2。指定 0 表示不縮排。

'exampleindent'
範例或文字區塊的行要縮排的空格數，預設值為 4。指定 0 表示不縮排。

'preamble'
Texinfo 標記，插入在檔案開頭附近。

'copying'
Texinfo 標記，插入在 @copying 區塊內，並在標題後顯示。預設值包含一個簡單的標題頁，用於識別專案。
由其他選項設定，因此不應覆寫的鍵為 'author'、'body'、'date'、'direntry' 'filename'、'project'、'release' 和 'title'。

版本 1.1 新增。

texinfo_no_detailmenu¶

類型:: bool
預設:: False

不要在「頂層」節點的選單中產生 @detailmenu，其中包含文件中每個子節點的項目。

在 1.2 版本加入。

texinfo_show_urls¶

類型:: 'footnote' | 'no' | 'inline'
預設:: 'footnote'

控制如何顯示 URL 位址。設定可以有以下值

'footnote': 在註腳中顯示 URL。
'no': 不顯示 URL。
'inline': 以括號內嵌顯示 URL。

版本 1.1 新增。

QtHelp 輸出選項¶

這些選項會影響 qthelp 輸出。此建置器衍生自 HTML 建置器，因此 HTML 選項也適用於適當情況。

qthelp_basename¶

類型:: 字串
預設:: project 的值

qthelp 檔案的基名。

qthelp_namespace¶

類型:: 字串
預設:: 'org.sphinx.{project_name}.{project_version}'

qthelp 檔案的命名空間。

qthelp_theme¶

類型:: 字串
預設:: 'nonav'

qthelp 輸出的 HTML 主題。

qthelp_theme_options¶

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

一個選項字典，用於影響所選主題的外觀和風格。這些選項是主題特定的。在內建主題中可理解的選項已在此處說明。

XML 輸出選項¶

xml_pretty¶

類型:: bool
預設:: True

美化列印 XML。

在 1.2 版本加入。

linkcheck 建置器的選項¶

篩選¶

這些選項控制 linkcheck 建置器檢查哪些連結，以及忽略哪些失敗和重新導向。

linkcheck_allowed_redirects¶

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

一個字典，將來源 URI 的模式對應到正規 URI 的模式。當符合以下條件時，linkcheck 建置器會將重新導向的連結視為「運作中」：

文件中的連結符合來源 URI 模式，且
重新導向位置符合正規 URI 模式。

當 linkcheck 建置器找到不符合上述規則的重新導向連結時，將會發出警告。當使用 fail-on-warnings 模式 時，這對於偵測意外的重新導向可能很有用。

範例

linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to
    # the canonical URI will be treated as "working".
    r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
}

版本 4.1 新增。

linkcheck_anchors¶

類型:: bool
預設:: True

檢查連結中 #anchor 的有效性。由於這需要下載整個文件，因此啟用時速度會明顯變慢。

在 1.2 版本加入。

linkcheck_anchors_ignore¶

類型:: Sequence[str]
預設:: ["^!"]

規則運算式清單，符合 linkcheck 建置器在檢查連結中錨點的有效性時應略過的錨點。例如，這允許略過網站 JavaScript 新增的錨點。

提示

使用 linkcheck_anchors_ignore_for_url 來檢查 URL，但略過驗證錨點是否存在。

注意

如果您想忽略特定頁面或符合特定模式的頁面的錨點（但仍然檢查相同頁面的出現次數，這些頁面沒有錨點），請改用 linkcheck_ignore，例如如下所示

linkcheck_ignore = [
   'https://sphinx-doc.dev.org.tw/en/1.7/intro.html#',
]

Added in version 1.5.

linkcheck_anchors_ignore_for_url¶

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

規則運算式清單或元組，符合 linkcheck 建置器不應檢查錨點有效性的 URL。這允許在逐頁基礎上略過錨點檢查，同時仍然檢查頁面本身的有效性。

版本 7.1 新增。

linkcheck_exclude_documents¶

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

規則運算式清單，符合 linkcheck 建置器不應檢查連結有效性的文件。這可以用於允許文件中舊版或歷史章節中的連結失效。

範例

# ignore all links in documents located in a subdirectory named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']

在 4.4 版本中新增。

linkcheck_ignore¶

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

規則運算式清單，符合在執行 linkcheck 建置時不應檢查的 URI。

伺服器發出的重新導向符合 忽略的 URI 將不會被跟隨。

範例

linkcheck_ignore = [r'https://127.0.0.1:\d+/']

版本 1.1 新增。

HTTP 請求¶

這些選項控制 linkcheck 建置器如何發出 HTTP 請求，包括如何處理重新導向和驗證，以及要使用的工作人員數量。

linkcheck_auth¶

類型:: Sequence[tuple[str, Any]]
預設:: []

在執行 linkcheck 建置時傳遞驗證資訊。

一個 (regex_pattern, auth_info) 元組清單，其中項目為

regex_pattern: 符合 URI 的規則運算式。
auth_info: 用於該 URI 的驗證資訊。該值可以是 requests 程式庫可以理解的任何內容（詳情請參閱 requests 驗證）。

linkcheck 建置器將使用它可以在 linkcheck_auth 清單中找到的第一個符合的 auth_info 值，因此清單中較早的值具有較高的優先順序。

範例

linkcheck_auth = [
  ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
  ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
]

Added in version 2.3.

linkcheck_allow_unauthorized¶

類型:: bool
預設:: False

當網路伺服器以 HTTP 401（未經授權）回應時，linkcheck 建置器目前的預設行為是將連結視為「已損壞」。若要變更該行為，請將此選項設定為 True。

在 8.0 版本中變更：此選項的預設值已變更為 False，表示預設情況下，對已檢查超連結的 HTTP 401 回應會被視為「已損壞」。

在 7.3 版本中新增。

linkcheck_rate_limit_timeout¶

類型:: int
預設:: 300

linkcheck 建置器可能會在短時間內向同一網站發出大量請求。當伺服器指示請求受到速率限制時，此設定會控制建置器的行為，方法是設定建置器在每次嘗試之間等待的最大持續時間（以秒為單位），然後再記錄失敗。

linkcheck 建置器始終尊重伺服器關於何時重試的指示（使用 Retry-After 標頭）。否則，linkcheck 會等待一分鐘後再重試，並保持每次嘗試之間的等待時間加倍，直到成功或超過 linkcheck_rate_limit_timeout（以秒為單位）。自訂逾時應以秒數給出。

在 3.4 版本中新增。

linkcheck_report_timeouts_as_broken¶

類型:: bool
預設:: False

如果在等待來自超連結的回應時 linkcheck_timeout 過期，則 linkcheck 建置器預設會將連結報告為 timeout。若要改為將逾時報告為 broken，您可以將 linkcheck_report_timeouts_as_broken 設定為 True。

在 8.0 版本中變更：此選項的預設值已變更為 False，表示檢查超連結時發生的逾時將使用新的「timeout」狀態代碼報告。

在 7.3 版本中新增。

linkcheck_request_headers¶

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

一個字典，將 URL（不含路徑）對應到 HTTP 請求標頭。

金鑰是一個 URL 基礎字串，例如 'https://sphinx-doc.dev.org.tw/'。若要為其他主機指定標頭，可以使用 "*"。僅當 URL 與其他設定不符時，它才會比對所有主機。

值是一個字典，將標頭名稱對應到其值。

範例

linkcheck_request_headers = {
    "https://sphinx-doc.dev.org.tw/": {
        "Accept": "text/html",
        "Accept-Encoding": "utf-8",
    },
    "*": {
        "Accept": "text/html,application/xhtml+xml",
    }
}

在 3.1 版本中新增。

linkcheck_retries¶

類型:: int
預設:: 1

linkcheck 建置器在宣告 URL 損壞之前將嘗試檢查 URL 的次數。

版本 1.4 新增。

linkcheck_timeout¶

類型:: int
預設:: 30

linkcheck 建置器在每次超連結請求後等待回應的持續時間，以秒為單位。

版本 1.1 新增。

linkcheck_workers¶

類型:: int
預設:: 5

檢查連結時要使用的工作執行緒數。

版本 1.1 新增。

網域選項¶

C 網域的選項¶

c_extra_keywords¶

類型:: Set[str] | Sequence[str]
預設:: ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local']

識別符號的清單，將被 C 語言解析器識別為關鍵字。

在 4.0.3 版本中新增。

變更於 7.4 版本：c_extra_keywords 現在可以是一個集合 (set)。

c_id_attributes¶

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

字串序列，解析器應額外接受為屬性。例如，當 #define 已被用於屬性時，為了可移植性，可以使用此選項。

範例

c_id_attributes = [
    'my_id_attribute',
]

在 3.0 版本中新增。

變更於 7.4 版本：c_id_attributes 現在可以是一個元組 (tuple)。

c_maximum_signature_line_length¶

類型:: int | None
預設:: None

如果簽名的字元長度超過設定的數字，則簽名中的每個參數都會顯示在個別的邏輯行上。

當 None 時，沒有最大長度，整個簽名將會顯示在單一邏輯行上。

這是一個網域特定的設定，會覆寫 maximum_signature_line_length。

版本 7.1 新增。

c_paren_attributes¶

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

字串序列，解析器應額外接受為帶有一個參數的屬性。也就是說，如果 my_align_as 在列表中，則對於所有具有平衡大括號 (()、[] 和 {}) 的字串 X，my_align_as(X) 會被解析為屬性。例如，當 #define 已被用於屬性時，為了可移植性，可以使用此選項。

範例

c_paren_attributes = [
    'my_align_as',
]

在 3.0 版本中新增。

變更於 7.4 版本：c_paren_attributes 現在可以是一個元組 (tuple)。

C++ 網域的選項¶

cpp_id_attributes¶

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

字串序列，解析器應額外接受為屬性。例如，當 #define 已被用於屬性時，為了可移植性，可以使用此選項。

範例

cpp_id_attributes = [
    'my_id_attribute',
]

Added in version 1.5.

變更於 7.4 版本：cpp_id_attributes 現在可以是一個元組 (tuple)。

cpp_index_common_prefix¶

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

前綴的清單，在全域索引中排序 C++ 物件時將被忽略。

範例

cpp_index_common_prefix = [
    'awesome_lib::',
]

Added in version 1.5.

cpp_maximum_signature_line_length¶

類型:: int | None
預設:: None

如果簽名的字元長度超過設定的數字，則簽名中的每個參數都會顯示在個別的邏輯行上。

當 None 時，沒有最大長度，整個簽名將會顯示在單一邏輯行上。

這是一個網域特定的設定，會覆寫 maximum_signature_line_length。

版本 7.1 新增。

cpp_paren_attributes¶

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

字串序列，解析器應額外接受為帶有一個參數的屬性。也就是說，如果 my_align_as 在列表中，則對於所有具有平衡大括號 (()、[] 和 {}) 的字串 X，my_align_as(X) 會被解析為屬性。例如，當 #define 已被用於屬性時，為了可移植性，可以使用此選項。

範例

cpp_paren_attributes = [
    'my_align_as',
]

Added in version 1.5.

變更於 7.4 版本：cpp_paren_attributes 現在可以是一個元組 (tuple)。

Javascript 網域的選項¶

javascript_maximum_signature_line_length¶

類型:: int | None
預設:: None

如果簽名的字元長度超過設定的數字，則簽名中的每個參數都會顯示在個別的邏輯行上。

當 None 時，沒有最大長度，整個簽名將會顯示在單一邏輯行上。

這是一個網域特定的設定，會覆寫 maximum_signature_line_length。

版本 7.1 新增。

javascript_trailing_comma_in_multi_line_signatures¶

類型:: bool
預設:: True

如果為 true，則在跨越多行的參數列表中使用尾隨逗號。

在 8.2 版本中新增。

Python 網域的選項¶

add_module_names¶

類型:: bool
預設:: True

一個布林值，決定是否將模組名稱前置到所有物件名稱（對於定義了某種「模組」的物件類型），例如對於 py:function 指令。

modindex_common_prefix¶

類型:: list[str]
預設:: []

前綴的清單，在排序 Python 模組索引時將被忽略 (例如，如果設定為 ['foo.']，則 foo.bar 會顯示在 B 下，而不是 F 下)。如果您記錄的專案由單一套件組成，這可能會很方便。

注意

目前僅適用於 HTML builder。

版本 0.6 新增。

python_display_short_literal_types¶

類型:: bool
預設:: False

此值控制 Literal 類型的顯示方式。

範例¶

以下範例使用以下 py:function 指令

.. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

當 False 時，Literal 類型會按照標準 Python 語法顯示，即：

serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

當 True 時，Literal 類型會以簡短的、PEP 604 啟發的語法顯示，即：

serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

在 6.2 版本中新增。

python_maximum_signature_line_length¶

類型:: int | None
預設:: None

如果簽名的字元長度超過設定的數字，則簽名中的每個參數都會顯示在個別的邏輯行上。

當 None 時，沒有最大長度，整個簽名將會顯示在單一邏輯行上。

這是一個網域特定的設定，會覆寫 maximum_signature_line_length。

對於 Python 網域，簽名長度取決於類型參數或引數列表是否正在格式化。對於前者，簽名長度會忽略引數列表的長度；對於後者，簽名長度會忽略類型參數列表的長度。

例如，使用 python_maximum_signature_line_length = 20，只有類型參數列表會被換行，而引數列表將在單行上呈現

.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

版本 7.1 新增。

python_trailing_comma_in_multi_line_signatures¶

類型:: bool
預設:: True

如果為 true，則在跨越多行的參數列表中使用尾隨逗號。

在 8.2 版本中新增。

python_use_unqualified_type_names¶

類型:: bool
預設:: False

如果可以解析，則抑制 python 參考的模組名稱。

在 4.0 版本中新增。

注意

此功能為實驗性質。

trim_doctest_flags¶

類型:: bool
預設:: True

移除行尾的 doctest 標誌 (看起來像 # doctest: FLAG, ... 的註解) 以及對於所有顯示互動式 Python 會話 (即 doctests) 的程式碼區塊的 <BLANKLINE> 標記。有關包含 doctest 的更多可能性，請參閱擴充功能 doctest。

Added in version 1.0.

變更於 1.1 版本：現在也移除 <BLANKLINE>。

擴充功能選項¶

擴充功能通常有自己的配置選項。Sphinx 第一方擴充功能的選項記錄在每個擴充功能頁面中。

範例設定檔¶

# -- Project information -----------------------------------------------------
# https://sphinx-doc.dev.org.tw/en/master/usage/configuration.html#project-information

project = 'Test Project'
copyright = '2000-2042, The Test Project Authors'
author = 'The Authors'
version = release = '4.16'

# -- General configuration ------------------------------------------------
# https://sphinx-doc.dev.org.tw/en/master/usage/configuration.html#general-configuration

exclude_patterns = [
    '_build',
    'Thumbs.db',
    '.DS_Store',
]
extensions = []
language = 'en'
master_doc = 'index'
pygments_style = 'sphinx'
source_suffix = '.rst'
templates_path = ['_templates']

# -- Options for HTML output ----------------------------------------------
# https://sphinx-doc.dev.org.tw/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']