sphinx-build¶
概要¶
sphinx-build [options] <sourcedir> <outputdir> [filenames …]
描述¶
sphinx-build 从 <sourcedir> 中的文件生成文档，并将文档放置在 <outputdir> 中。
sphinx-build 在 <sourcedir>/conf.py 中查找配置设置。可以使用 sphinx-quickstart(1) 生成模板文件，包括 conf.py。
sphinx-build 可以创建不同格式的文档。可以通过在命令行上指定构建器名称来选择格式；默认值为 HTML。构建器还可以执行与文档处理相关的其他任务。有关可用构建器的列表，请参阅 构建器。
默认情况下，所有过时的内容都会被构建。可以通过指定单个文件名来构建仅针对选定文件的输出。
选项¶
- -M buildername¶
使用make 模式选择构建器。请参阅 构建器 获取 Sphinx 所有内置构建器的列表。扩展可以添加自己的构建器。
重要提示
只有在使用make 模式时，并且它在任何其他选项传递之前，与源目录和输出目录一起使用时，Sphinx 才会识别
-M选项。例如sphinx-build -M html ./source ./build --fail-on-warning
make 模式提供与默认 Makefile 或 Make.bat 相同的构建功能，并提供以下附加构建管道
- latexpdf
构建 LaTeX 文件并通过 pdflatex 运行它们，或根据
latex_engine设置运行它们。如果language设置为'ja'，则将自动使用 platex/dvipdfmx latex 到 PDF 管道。- info
构建 Texinfo 文件并通过 makeinfo 运行它们。
注意
使用make 模式时的默认输出目录位置与使用
-b时的默认位置不同。doctrees 保存到
<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 腌制文件”。通常，这些文件被放置在构建目录下的名为
.doctrees的目录中；使用此选项，您可以选择不同的缓存目录（doctrees 可以由所有构建器共享）。在版本 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, --config-dir path¶
不要在源目录中查找
conf.py，而是使用给定的配置目录。请注意，配置值给出的各种其他文件和路径应该相对于配置目录，因此它们也必须存在于此位置。在版本 0.3 中添加。
在版本 7.3 中更改: 添加
--config-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¶
在 HTML 模板中将 name 分配给 value。
在版本 0.5 中添加。
版本 7.3 中变更： 添加
--html-define长选项。
- -n, --nitpicky¶
以 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 模式下调用子构建过程。
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或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)