Sphinx--构建¶
提纲¶
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只识别
-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
构建纹理信息文件并运行它们 makeinfo 。
备注
使用时的默认输出目录位置 make-mode 与使用时的默认值不同
-b.文档树保存到
<outputdir>/doctrees输出文件保存到
<outputdir>/<builder name>
Added in version 1.2.1.
- -b buildername, --builder buildername¶
指定构建器。
看到 构建器 获取狮身星所有内置构建器的列表。扩展可以添加自己的构建器。
在 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 了解更多细节。Added in version 0.6.
在 7.3 版本发生变更: 添加
--tag长期选择。
- -d path, --doctree-dir path¶
由于Sphinx必须读取并解析所有源文件，然后才能写入输出文件，因此解析后的源文件将被缓存为“Doctree Pickle”。通常，这些文件放在一个名为
.doctrees在构建目录下；使用此选项，您可以选择不同的缓存目录(文档树可以在所有构建器之间共享)。在 7.3 版本发生变更: 添加
--doctree-dir长期选择。
- -j N, --jobs N¶
将构建分发到 N 并行处理，使在多处理器机器上构建更加有效。此功能仅适用于支持“fork”的系统。不支持Windows。请注意，并非Sphinx的所有部分和所有构建者都可以并行化。如果
auto给定参数时，Sphinx使用中央处理器数量作为 N .返回至1。Added in version 1.2: 应考虑此选项 experimental 。
在 1.7 版本发生变更: 支持
auto争论。在 6.2 版本发生变更: 增列
--jobs长时间的选择。
- -c path, --conf-dir path¶
别去找那些
conf.py在源目录中，但改用给定的配置目录。请注意，由配置值提供的各种其他文件和路径预计都是相对于配置目录的，因此它们也必须位于此位置。Added in version 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¶
使之成为 name 分配给 value 在HTML模板中。
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 版本发生变更: 写入时，将剥离ASIC控制序列 file .
在 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¶
从Sphinx8.1开始，
--keep-going始终启用。以前，它仅适用于使用时--fail-on-warning，默认退出 sphinx-build 在第一次警告时。使用--keep-going运行 sphinx-build 完成，如果遇到错误，则退出状态为1。Added in version 1.8.
在 8.1 版本发生变更: sphinx-build 不再在第一次警告时退出，这意味着实际上
--keep-going始终启用。保留该选项是为了兼容性，但可能会在以后删除。
- -T, --show-traceback¶
当发生未处理的异常时显示完整的回溯。否则，将仅显示摘要，并将回溯信息保存到文件中以供进一步分析。
Added in version 1.2.
在 7.3 版本发生变更: 添加
--show-traceback长期选择。
- -h, --help, --version¶
显示使用情况摘要或Sphinx版本。
Added in version 1.2.
您还可以在命令行中的源代码和构建目录之后指定一个或多个文件名。然后，Sphinx将尝试仅构建这些输出文件(及其依赖项)。
环境变量¶
这个 sphinx-build 指的是以下环境变量：
- MAKE
一条下达命令的路径。命令名也是允许的。 sphinx-build 使用它在生成模式上调用子生成过程。
生成文件选项
这个 Makefile 和 make.bat 文件创建者 sphinx-quickstart 通常跑步 sphinx-build 仅限使用 -b 和 -d 选择。但是，它们支持以下变量以自定义行为：
- PAPER
这将设置
'papersize'的关键字latex_elements：即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_COLORtakes precedence overFORCE_COLOR. See no-color.org 用于支持此社区标准的其他类库。Added in version 4.5.0.
- FORCE_COLOR
设置时(无论值如何)， 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)