sphinx-build¶
概要¶
sphinx-build [選項] <sourcedir> <outputdir> [filenames …]
描述¶
sphinx-build 從 <sourcedir> 中的檔案產生文件，並將其放置在 <outputdir> 中。
sphinx-build 會在 <sourcedir>/conf.py 中尋找設定檔。sphinx-quickstart(1) 可用於產生範本檔案，包括 conf.py。
sphinx-build 可以建立不同格式的文件。透過在命令列上指定建置器名稱來選擇格式；預設為 HTML。建置器也可以執行與文件處理相關的其他任務。如需可用建置器的清單，請參閱建置器。
預設情況下，會建置所有過期的內容。僅針對選定的檔案輸出可以透過指定個別檔案名稱來建置。
選項¶
- -M buildername¶
選擇一個建置器，使用make-mode。請參閱建置器以取得所有 Sphinx 內建建置器的清單。擴充功能可以新增它們自己的建置器。
重要
Sphinx 僅在
-M選項與來源目錄和輸出目錄一起首先使用，然後才傳遞任何其他選項時，才會識別它。例如sphinx-build -M html ./source ./build --fail-on-warning
make-mode 提供與預設 Makefile 或 Make.bat 相同的建置功能，並提供以下額外的建置管線
- latexpdf
建置 LaTeX 檔案並透過 pdflatex 執行它們，或按照
latex_engine設定。如果language設定為'ja'，將自動使用 platex/dvipdfmx latex 到 PDF 管線。- info
建置 Texinfo 檔案並透過 makeinfo 執行它們。
注意
使用 make-mode 時的預設輸出目錄位置與使用
-b時的預設值不同。doctree 會儲存到
<outputdir>/doctrees輸出檔案會儲存到
<outputdir>/<builder name>
在版本 1.2.1 中新增。
- -b buildername, --builder buildername¶
選擇建置器。
請參閱建置器以取得所有 Sphinx 內建建置器的清單。擴充功能可以新增它們自己的建置器。
版本 7.3 中變更: 新增
--builder長選項。
- -a, --write-all¶
如果給定此選項，則始終寫入所有輸出檔案。預設值是僅針對新的和變更的來源檔案寫入輸出檔案。（這可能不適用於所有建置器。）
注意
此選項不會重新讀取來源檔案。要讀取並重新處理每個檔案，請改用
--fresh-env。版本 7.3 中變更: 新增
--write-all長選項。
- -E, --fresh-env¶
不要使用已儲存的環境（快取所有交叉參照的結構），而是完全重建它。預設值是僅讀取和解析自上次執行以來是新的或已變更的來源檔案。
版本 7.3 中變更: 新增
--fresh-env長選項。
- -t tag, --tag tag¶
定義標籤tag。這與
only指令相關，這些指令僅在設定特定標籤時才包含其內容。請參閱根據標籤包含內容以取得更多詳細資訊。在版本 0.6 中新增。
版本 7.3 中變更: 新增
--tag長選項。
- -d path, --doctree-dir path¶
由於 Sphinx 必須先讀取和解析所有來源檔案，然後才能寫入輸出檔案，因此解析後的來源檔案會快取為「doctree pickles」。通常，這些檔案會放在建置目錄下名為
.doctrees的目錄中；使用此選項，您可以選擇不同的快取目錄（doctree 可以在所有建置器之間共享）。版本 7.3 中變更: 新增
--doctree-dir長選項。
- -j N, --jobs N¶
在 N 個程序中平行分配建置，以使在多處理器機器上建置更有效率。此功能僅適用於支援「fork」的系統。不支援 Windows。請注意，並非 Sphinx 的所有部分和所有建置器都可以平行化。如果給定
auto引數，Sphinx 會使用 CPU 數量作為 N。預設值為 1。在版本 1.2 中新增: 此選項應視為實驗性。
版本 1.7 中變更: 支援
auto引數。版本 6.2 中變更: 新增
--jobs長選項。
- -c path, --conf-dir path¶
不要在來源目錄中尋找
conf.py，而是改用給定的設定目錄。請注意，組態值給定的各種其他檔案和路徑預期與設定目錄相對，因此它們也必須位於此位置。在版本 0.3 中新增。
版本 7.3 中變更: 新增
--conf-dir長選項。
- -D setting=value, --define setting=value¶
覆寫在
conf.py檔案中設定的組態值。值必須是數字、字串、清單或字典值。對於清單，您可以使用逗號分隔元素，例如：
-D html_theme_path=path1,path2。對於字典值，請提供設定名稱和索引鍵，例如：
-D latex_elements.docclass=scrartcl。對於布林值，請使用
0或1作為值。版本 0.6 中變更: 值現在可以是字典值。
版本 1.3 中變更: 值現在也可以是清單值。
版本 7.3 中變更: 新增
--define長選項。
- -A name=value, --html-define name=value¶
使name 在 HTML 範本中分配給 value。
在版本 0.5 中新增。
版本 7.3 中變更: 新增
--html-define長選項。
- -n, --nitpicky¶
在吹毛求疵模式下執行。目前，這會為所有遺失的參考產生警告。請參閱組態值
nitpick_ignore，以排除一些參考作為「已知遺失」。版本 7.3 中變更: 新增
--nitpicky長選項。
- -N, --no-color¶
不要發出彩色輸出。
版本 1.6 中變更: 新增
--no-color長選項。
- --color¶
發出彩色輸出。預設為自動偵測。
在版本 1.6 中新增。
- -v, --verbose¶
增加詳細程度（日誌層級）。可以給定此選項最多三次以取得更多偵錯日誌輸出。它暗示
-T。在版本 1.2 中新增。
版本 7.3 中變更: 新增
--verbose長選項。
- -q, --quiet¶
不要在標準輸出上輸出任何內容，僅將警告和錯誤寫入標準錯誤。
版本 7.3 中變更: 新增
--quiet長選項。
- -Q, --silent¶
不要在標準輸出上輸出任何內容，也抑制警告。僅錯誤會寫入標準錯誤。
版本 7.3 中變更: 新增
--silent長選項。
- -w file, --warning-file file¶
除了標準錯誤之外，還將警告（和錯誤）寫入給定的檔案。
版本 7.3 中變更: 在寫入file 時，會剝離 ANSI 控制序列。
版本 7.3 中變更: 新增
--warning-file長選項。
- -W, --fail-on-warning¶
將警告轉換為錯誤。這表示如果在建置期間產生任何警告，sphinx-build 將以結束狀態 1 結束。
版本 7.3 中變更: 新增
--fail-on-warning長選項。版本 8.1 中變更: sphinx-build 不再在第一個警告時結束，而是執行整個建置，並且如果產生任何警告，則以結束狀態 1 結束。此行為先前已透過
--keep-going啟用。
- --keep-going¶
從 Sphinx 8.1 開始，
--keep-going始終啟用。先前，它僅在使用--fail-on-warning時適用，預設情況下，它會在第一個警告時結束 sphinx-build。使用--keep-going會執行 !sphinx-build 直到完成，並且如果遇到錯誤，則以結束狀態 1 結束。在版本 1.8 中新增。
版本 8.1 中變更: sphinx-build 不再在第一個警告時結束，這表示實際上
--fail-on-warning始終啟用。此選項保留用於相容性，但可能會在稍後日期移除。
- -T, --show-traceback¶
當發生未處理的例外狀況時，顯示完整的追溯。否則，僅顯示摘要，並且追溯資訊會儲存到檔案中以供進一步分析。
在版本 1.2 中新增。
版本 7.3 中變更: 新增
--show-traceback長選項。
- -h, --help, --version¶
顯示使用摘要或 Sphinx 版本。
在版本 1.2 中新增。
您也可以在來源和建置目錄之後的命令列上給定一個或多個檔案名稱。然後，Sphinx 將嘗試僅建置這些輸出檔案（及其相依性）。
環境變數¶
sphinx-build 參考以下環境變數
- MAKE
make 命令的路徑。也允許命令名稱。sphinx-build 使用它在 make-mode 上調用子建置程序。
Makefile 選項
由 sphinx-quickstart 建立的 Makefile 和 make.bat 檔案通常僅使用 -b 和 -d 選項執行 sphinx-build。但是，它們支援以下變數來自訂行為
- PAPER
這會設定
latex_elements的'papersize'索引鍵：即PAPER=a4將其設定為'a4paper'，PAPER=letter設定為'letterpaper'。注意
此環境變數的用法在 Sphinx 1.5 中被破壞，因為
a4或letter最終成為 LaTeX 文件中的選項，而不是所需的a4paper，resp.letterpaper。在 1.7.7 中修復。
- SPHINXBUILD
要使用的命令，而不是
sphinx-build。
- BUILDDIR
要使用的建置目錄，而不是在 sphinx-quickstart 中選擇的目錄。
- SPHINXOPTS
sphinx-build 的其他選項。這些選項也可以透過快捷變數 O （大寫「O」）設定。
- NO_COLOR
設定後（無論值為何），sphinx-build 將不會在終端輸出中使用顏色。
NO_COLOR優先於FORCE_COLOR。請參閱 no-color.org 以取得其他支援此社群標準的程式庫。在版本 4.5.0 中新增。
- FORCE_COLOR
設定後（無論值為何），sphinx-build 將在終端輸出中使用顏色。
NO_COLOR優先於FORCE_COLOR。在版本 4.5.0 中新增。
棄用警告¶
如果在建置使用者文件時顯示任何棄用警告，例如 RemovedInSphinxXXXWarning，則表示某些 Sphinx 擴充功能正在使用已棄用的功能。在這種情況下，請向擴充功能的作者報告。
要停用棄用警告，請將 PYTHONWARNINGS= 環境變數設定為您的環境。例如
PYTHONWARNINGS= make html(Linux/Mac)export PYTHONWARNINGS=並執行make html(Linux/Mac)set PYTHONWARNINGS=並執行make html(Windows)修改您的 Makefile/make.bat 並設定環境變數
參見¶
sphinx-quickstart(1)