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-mode。有关 Sphinx 所有内置构建器的列表，请参阅 构建器。
重要
Sphinx 仅在首先使用
-M选项时才会识别它, 以及源和输出目录, 在传递任何其他选项之前。例如:sphinx-build -M html ./source ./build --fail-on-warning
make-mode 提供与默认 Makefile or Make.bat 相同的生成 功能，并提供以下附加生成管道：
- latexpdf
生成 LaTeX 文件并通过 pdflatex 或
latex_engine设置运行。如果language设置为“'ja'”，将自动使用 platex/dvipdfmx latex来生成PDF通道。- info
生成 Texinfo 文件并通过 makeinfo 运行它们。
- help
输出有效的构建器目标列表，然后退出。
备注
默认输出目录位置在使用 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¶
不使用已保存的 environment （其中缓存了交叉引用列表），每次都要重新生成。默认是只读取和处理新的或者上次运行之后有改动的文件。
在 7.3 版本发生变更: 增加
--fresh-env长选项。
- -t tag, --tag tag¶
定义标签 tag。这与
only指令相关，只有在设置了某些标签时才包含其内容。有关更多详细信息，请参阅 including content based on tags。在 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¶
在 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 版本发生变更: 写入 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 不再在第一个警告时退出，这意味着实际上
--keep-going总是启用的。该选项被保留以保持兼容性，但可能会在以后的某个日期被删除。
- -T, --show-traceback¶
遇到未处理的异常时，显示完整的跟踪记录（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 文件，调用 sphinx-build 时，通常只有 -b 和 -d 两个选项。不过它们也支持如下变量来定制他们的操作：
- PAPER
这设置了
latex_elements中的'papersize'键：即PAPER=a4将它设置为'a4paper'并将PAPER=letter设置为'letterpaper'。备注
这个环境变量的使用在Sphinx 1.5中被打断了，因为
a4或letter最终被用来替代所需的a4paper（A4纸）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 系统）修改 Makefilie 和/或 make.bat 文件，设置其中的环境变量
另请参阅¶
sphinx-quickstart(1)