sphinx-build¶
提要¶
sphinx-build [选项] <源目录> <输出目录> [文件名 …]
描述¶
sphinx-build 从 <源目录> 中的文件生成文档，并将其放置在 <输出目录> 中。
sphinx-build 在 <源目录>/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 管道。- 信息
构建 Texinfo 文件并将其通过 makeinfo 运行。
- 帮助
输出有效构建器目标的列表，然后退出。
注意
使用 make-mode 时的默认输出目录位置与使用
-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 pickles”。通常，这些文件放在构建目录下的名为
.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, --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¶
在 HTML 模板中将 name 赋值给 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 中更改： 写入 文件 时，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 不再在第一个警告时退出，这意味着
--keep-going实际上始终启用。此选项为了兼容性而保留，但可能会在以后移除。
- -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)