sphinx-build¶

概要¶

sphinx-build [选项] <源目录> <输出目录> [文件名 …]

描述¶

sphinx-build 从 <sourcedir> 中的文件生成文档,并将其放置在 <outputdir> 中.

sphinx-build 在 <sourcedir>/conf.py 中查找配置设置.:manpage: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>

Added in version 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 指令是相关的.有关更多详细信息,请参见基于标签包含内容.

Added in version 0.6.

在 7.3 版本发生变更: 添加 --tag 长选项.

-d path, --doctree-dir path¶: 由于Sphinx在写入输出文件之前必须读取和解析所有源文件,解析后的源文件被缓存为”doctree pickles”.通常,这些文件被放置在构建目录下的一个名为 .doctrees 的目录中;通过此选项,您可以选择不同的缓存目录（doctree可以在所有构建器之间共享）.

在 7.3 版本发生变更: 添加 --doctree-dir 长选项.

-j N, --jobs N¶: 在 N 个进程中并行分配构建,以使多处理器机器上的构建更有效.请注意,并非所有部分和所有构建器都可以并行化.如果给出了 auto 参数,Sphinx 将使用 CPU 数量作为 N.默认为 1.

Added in version 1.2: 此选项应被视为*实验性*.

在 1.7 版本发生变更: 支持 auto 参数.

在 6.2 版本发生变更: 添加 --jobs 长选项.

-c path, --config-dir path¶: 不要在源目录中寻找 conf.py ,而是使用给定的配置目录.请注意,配置值给出的各种其他文件和路径预计是相对于配置目录的,因此它们也必须存在于该位置.

Added in version 0.3.

在 7.3 版本发生变更: 添加 --config-dir 长选项.

-C, --isolated¶: 不要寻找配置文件;只通过 --define 选项获取选项.

Added in version 0.5.

在 7.3 版本发生变更: 添加 --isolated 长选项.

-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*.

Added in version 0.5.

在 7.3 版本发生变更: 添加 --html-define 长选项.

-n, --nitpicky¶: 以吹毛求疵模式运行.目前,这会为所有缺失的引用生成警告.有关排除某些引用为”已知缺失”的方法,请参见配置值 nitpick_ignore.

在 7.3 版本发生变更: 添加 --nitpicky 长选项.

-N, --no-color¶: 不要发出彩色输出.

在 1.6 版本发生变更: 添加 --no-color 长选项.

--color¶: 发出彩色输出.默认情况下自动检测.

Added in version 1.6.

-v, --verbose¶: 增加详细程度（日志级别）.这个选项最多可以给出三次以获得更多的调试日志输出.它隐含 -T.

Added in version 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¶: 将警告转换为错误.这意味着如果构建过程中生成任何警告,:program:sphinx-build 将以退出状态 1 退出.

在 7.3 版本发生变更: 添加 --fail-on-warning 长选项.

在 8.1 版本发生变更: sphinx-build 不再在第一次警告时退出,而是运行整个构建并在生成任何警告时以退出状态 1 退出.此行为以前是通过 --keep-going 启用的.

--keep-going¶: 从 Sphinx 8.1 开始,:option:!–keep-going 总是启用.以前,它仅在使用 --fail-on-warning 时适用,默认情况下在第一次警告时退出 sphinx-build.使用 --keep-going 运行 !sphinx-build 直到完成,并在遇到错误时以退出状态 1 退出.

Added in version 1.8.

在 8.1 版本发生变更: sphinx-build 不再在第一个警告时退出,这意味着实际上 --fail-on-warning 总是启用的.该选项保留以保持兼容性,但可能会在未来的某个日期被移除.

-T, --show-traceback¶: 当发生未处理的异常时,显示完整的回溯信息.否则,只显示摘要,并将回溯信息保存到文件中以供进一步分析.

Added in version 1.2.

在 7.3 版本发生变更: 添加 --show-traceback 长选项.

-P, --pdb¶: （仅用于调试.）如果在构建过程中发生未处理的异常,则运行 Python 调试器 pdb.

在 7.3 版本发生变更: 添加 --pdb 长选项.

--exception-on-warning¶: 在构建过程中发出警告时引发异常.这在与 --pdb 结合使用时非常有用,可以调试警告.

Added in version 8.1.

-h, --help, --version¶: 显示使用摘要或 Sphinx 版本.

Added in version 1.2.

你也可以在命令行中在源目录和构建目录之后指定一个或多个文件名.Sphinx 将尝试仅构建这些输出文件（及其依赖项）.

环境变量¶

sphinx-build 引用以下环境变量:

MAKE: 一个用于make命令的路径.也允许使用命令名称.:program: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: 当设置时（无论值如何）,:program:sphinx-build 将不在终端输出中使用颜色.``NO_COLOR`` 优先于 FORCE_COLOR.请参阅 no-color.org 以获取支持此社区标准的其他库.

Added in version 4.5.0.

FORCE_COLOR: 当设置时（无论值如何）,:program:sphinx-build 将在终端输出中使用颜色.``NO_COLOR`` 优先于 FORCE_COLOR.

Added in version 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)