Sphinx建筑¶
简介¶
sphinx-build [options] < 苏塞迪尔 > 输出输出 > [filenames ...]
描述¶
sphinx-build 从中的文件生成文档 <sourcedir> 把它放在 <outputdir> .
sphinx-build 寻找 <sourcedir>/conf.py 用于配置设置。 sphinx-quickstart(1) 可用于生成模板文件，包括 conf.py .
sphinx-build 可以创建不同格式的文档。通过在命令行上指定构建器名称来选择一种格式；它缺省为HTML。构建器还可以执行与文档处理相关的其他任务。有关可用构建器的列表，请参阅 Builders 。
默认情况下，会生成所有过时的内容。只能通过指定单个文件名来生成选定文件的输出。
选项¶
- -M buildername¶
选择一个构建器，使用 make-mode 。看见 Builders 获取Sphinx所有内置构建器的列表。扩展可以添加自己的构建器。
重要
Sphinx只识别
-M选项(如果在传递任何其他选项之前首先与源目录和输出目录一起使用)。例如：：sphinx-build -M html ./source ./build -W --keep-going
这个 make-mode 提供与默认生成功能相同的生成功能 Makefile or Make.bat ，并提供以下附加生成管道：
- latexpdf
生成 Latex 文件并运行它们 pdflatex ，或按
latex_engine设置。如果language设置为'ja'，将自动使用 platex/dvipdfmx Latex 到PDF管道。- info
构建texinfo文件并运行它们 makeinfo .
备注
使用时的默认输出目录位置 make-mode 与使用时的默认设置不同
-b。文档树保存到
<outputdir>/doctrees输出文件保存到
<outputdir>/<builder name>
Added in version 1.2.1.
- -b buildername, --builder buildername¶
选择构建器。
看见 Builders 获取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仅包含其内容（如果设置了此标记）的指令。Added in version 0.6.
在 7.3 版本发生变更: 增列
--tag长时间的选择。
- -d path, --doctree-dir path¶
由于sphinx必须在写入输出文件之前读取和解析所有源文件，因此解析的源文件缓存为“doctree pickles”。通常，这些文件放在一个名为
.doctrees在build目录下；使用此选项，可以选择其他缓存目录（doctrees可以在所有生成器之间共享）。在 7.3 版本发生变更: 增列
--doctree-dir长时间的选择。
- -j N, --jobs N¶
分发构建 N 并行处理，使多处理器机器上的构建更有效。请注意，不是所有的部分，也不是所有的Sphinx建筑商都可以平行。如果
auto参数是给定的，sphinx使用CPU的数量作为 N .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¶
使 name 指派给 价值 在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 版本发生变更: 写入时，ANSI控制序列被剥离 file 。
在 7.3 版本发生变更: 增列
--warning-file长时间的选择。
- -W, --fail-on-warning¶
把警告变成错误。这意味着构建将在第一个警告时停止，并且
sphinx-build退出状态为1。在 7.3 版本发生变更: 增列
--fail-on-warning长时间的选择。
- --keep-going¶
使用-w选项，在生成结束时继续处理警告，以及
sphinx-build退出状态为1。Added in version 1.8.
- -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，RESP。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)