sphinx-build¶
概要¶
sphinx-build [选项] <源目录> <输出目录> [文件名 …]
描述¶
sphinx-build 从 <源目录> 中的文件生成文档，并将其放置在 <输出目录> 中。
sphinx-build 在 <源目录>/conf.py 中查找配置设置。可以使用 sphinx-quickstart(1) 生成模板文件，包括 conf.py。
sphinx-build 可以创建不同格式的文档。通过在命令行上指定构建器名称来选择格式；默认格式为 HTML。构建器还可以执行与文档处理相关的其他任务。有关可用构建器的列表，请参阅 构建器。
默认情况下，会构建所有过时的内容。仅针对选定文件的输出可以通过指定单个文件名来构建。
选项¶
- -M 构建器名称¶
选择构建器，使用 make-mode 模式。 有关 Sphinx 所有内置构建器的列表，请参阅 构建器。扩展可以添加它们自己的构建器。
重要
仅当
-M选项与源目录和输出目录一起首先使用，然后在传递任何其他选项之前，Sphinx 才会识别它。例如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 运行它们。
在 1.2.1 版本中添加。
- -b 构建器名称, --builder 构建器名称¶
选择一个构建器。
有关 Sphinx 所有内置构建器的列表，请参阅 构建器。扩展可以添加它们自己的构建器。
在 7.3 版本中更改: 添加
--builder长选项。
- -a, --write-all¶
如果给定，始终写入所有输出文件。默认情况下，仅写入新的和已更改的源文件的输出文件。（这可能不适用于所有构建器。）
注意
此选项不会重新读取源文件。要读取和重新处理每个文件，请改用
--fresh-env。在 7.3 版本中更改: 添加
--write-all长选项。
- -E, --fresh-env¶
不使用已保存的 环境（缓存所有交叉引用的结构），而是完全重建它。默认情况下，仅读取和解析自上次运行以来是新的或已更改的源文件。
在 7.3 版本中更改: 添加
--fresh-env长选项。
- -t 标签, --tag 标签¶
定义标签 tag。这与
only指令相关，这些指令仅在设置了某些标签时才包含其内容。有关更多详细信息，请参阅 根据标签包含内容。在 0.6 版本中添加。
在 7.3 版本中更改: 添加
--tag长选项。
- -d 路径, --doctree-dir 路径¶
由于 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 路径, --conf-dir 路径¶
不要在源目录中查找
conf.py，而是使用给定的配置目录。请注意，配置值给出的各种其他文件和路径都应相对于配置目录，因此它们也必须位于此位置。在 0.3 版本中添加。
在 7.3 版本中更改: 添加
--conf-dir长选项。
- -D 设置=值, --define 设置=值¶
覆盖在
conf.py文件中设置的配置值。该值必须是数字、字符串、列表或字典值。对于列表，您可以使用逗号分隔元素，如下所示：
-D html_theme_path=path1,path2。对于字典值，请提供设置名称和键，如下所示：
-D latex_elements.docclass=scrartcl。对于布尔值，请使用
0或1作为值。在 0.6 版本中更改: 该值现在可以是字典值。
在 1.3 版本中更改: 该值现在也可以是列表值。
在 7.3 版本中更改: 添加
--define长选项。
- -A 名称=值, --html-define 名称=值¶
使 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 文件, --warning-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或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)