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。构建器还可以执行与文档处理相关的其他任务。有关可用构建器的列表,请参阅 Builders。
默认情况下,所有过时的内容都会被构建。通过指定单个文件名,可以仅构建选定文件的输出。
选项¶
- -M buildername¶
使用 make 模式 选择构建器。有关 Sphinx 所有内置构建器的列表,请参阅 Builders。扩展可以添加自己的构建器。
Important
Sphinx 仅在首先使用
-M
选项时识别它,并且它必须与源目录和输出目录一起使用,然后才能传递其他选项。例如:sphinx-build -M html ./source ./build --fail-on-warning
make 模式 提供了与默认的 Makefile 或 Make.bat 相同的构建功能,并提供了以下额外的构建管道:
- latexpdf
构建 LaTeX 文件并通过 pdflatex 运行它们,或根据
latex_engine
设置运行。如果language
设置为'ja'
,将自动使用 platex/dvipdfmx latex 到 PDF 管道。- info
构建 Texinfo 文件并通过 makeinfo 运行它们。
Note
使用 make 模式 时的默认输出目录位置与使用
-b
时的默认位置不同。文档树保存到
<outputdir>/doctrees
输出文件保存到
<outputdir>/<builder name>
Added in version 1.2.1.
- -b buildername, --builder buildername¶
选择构建器。
有关 Sphinx 所有内置构建器的列表,请参阅 Builders。插件可以添加自己的构建器。
Changed in version 7.3: 添加
--builder
长选项。
- -a, --write-all¶
如果指定,则始终写入所有输出文件。默认情况下,仅为新文件和更改的源文件写入输出文件。(这可能不适用于所有构建器。)
Note
此选项不会重新读取源文件。要读取并重新处理每个文件,请使用
--fresh-env
。Changed in version 7.3: 添加
--write-all
长选项。
- -E, --fresh-env¶
不使用保存的 environment (缓存所有交叉引用的结构),而是完全重新构建它。默认情况下,仅读取和解析自上次运行以来新增或更改的源文件。
Changed in version 7.3: 添加
--fresh-env
长选项。
- -t tag, --tag tag¶
定义标签 tag。这与
only
指令相关,这些指令仅在设置了某些标签时才会包含其内容。有关更多详细信息,请参阅 基于标签包含内容。Added in version 0.6.
Changed in version 7.3: 添加
--tag
长选项。
- -d path, --doctree-dir path¶
由于 Sphinx 在写入输出文件之前必须读取和解析所有源文件,因此解析后的源文件会被缓存为“文档树 pickle”。通常,这些文件会放在构建目录下的
.doctrees
目录中;使用此选项,您可以选择不同的缓存目录(文档树可以在所有构建器之间共享)。Changed in version 7.3: 添加
--doctree-dir
长选项。
- -j N, --jobs N¶
将构建分布在 N 个并行进程中,以便在多处理器机器上更有效地进行构建。此功能仅在支持“fork”的系统上有效。不支持 Windows。请注意,并非 Sphinx 的所有部分和所有构建器都可以并行化。如果给出
auto
参数,Sphinx 将使用 CPU 的数量作为 N。默认为 1。Added in version 1.2: 此选项应被视为 实验性。
Changed in version 1.7: 支持
auto
参数。Changed in version 6.2: 添加
--jobs
长选项。
- -c path, --conf-dir path¶
不要在源目录中查找
conf.py
,而是使用给定的配置目录。请注意,配置值给出的各种其他文件和路径应相对于配置目录,因此它们也必须存在于该位置。Added in version 0.3.
Changed in version 7.3: 添加
--conf-dir
长选项。
- -C, --isolated¶
不要查找配置文件;仅通过
--define
选项获取选项。Added in version 0.5.
Changed in version 7.3: 添加
--isolated
长选项。
- -D setting=value, --define setting=value¶
覆盖
conf.py
文件中设置的配置值。该值必须是数字、字符串、列表或字典值。对于列表,您可以用逗号分隔元素,例如:
-D html_theme_path=path1,path2
。对于字典值,请提供设置名称和键,例如:
-D latex_elements.docclass=scrartcl
。对于布尔值,使用
0
或1
作为值。Changed in version 0.6: 该值现在可以是字典值。
Changed in version 1.3: 该值现在也可以是列表值。
Changed in version 7.3: 添加
--define
长选项。
- -A name=value, --html-define name=value¶
在 HTML 模板中将 name 赋值为 value。
Added in version 0.5.
Changed in version 7.3: 添加
--html-define
长选项。
- -n, --nitpicky¶
以 nitpicky 模式运行。目前,这会为所有缺失的引用生成警告。有关排除某些引用为“已知缺失”的方法,请参阅配置值
nitpick_ignore
。Changed in version 7.3: 添加
--nitpicky
长选项。
- -N, --no-color¶
不输出彩色内容。
Changed in version 1.6: 添加
--no-color
长选项。
- --color¶
输出彩色内容。默认情况下自动检测。
Added in version 1.6.
- -v, --verbose¶
增加详细程度(日志级别)。此选项最多可以给出三次,以获得更多的调试日志输出。它隐含了
-T
。Added in version 1.2.
Changed in version 7.3: 添加
--verbose
长选项。
- -q, --quiet¶
不在标准输出上输出任何内容,仅将警告和错误写入标准错误。
Changed in version 7.3: 添加
--quiet
长选项。
- -Q, --silent¶
不在标准输出上输出任何内容,也抑制警告。仅将错误写入标准错误。
Changed in version 7.3: 添加
--silent
长选项。
- -w file, --warning-file file¶
将警告(和错误)写入给定的文件,而不仅仅是标准错误。
Changed in version 7.3: ANSI 控制序列在写入 file 时会被删除。
Changed in version 7.3: 添加
--warning-file
长选项。
- -W, --fail-on-warning¶
将警告转换为错误。这意味着如果构建过程中生成了任何警告,sphinx-build 将以退出状态 1 退出。
Changed in version 7.3: 添加
--fail-on-warning
长选项。Changed in version 8.1: :program:sphinx-build 不再在第一个警告时退出,而是运行整个构建并在有任何警告生成时以退出状态 1 退出。此行为以前是通过
--keep-going
启用的。
- --keep-going¶
从 Sphinx 8.1 开始,
--keep-going
始终启用。以前,它仅适用于--fail-on-warning
,默认情况下在第一个警告时退出 sphinx-build。使用--keep-going
运行 !sphinx-build 以完成并在遇到错误时以退出状态 1 退出。Added in version 1.8.
Changed in version 8.1: sphinx-build 不再在第一个警告时退出,这意味着在效果上
--fail-on-warning
始终启用。
- -T, --show-traceback¶
显示未处理异常的完整回溯。否则,仅显示摘要,并将回溯信息保存到文件中以供进一步分析。
Added in version 1.2.
Changed in version 7.3: 添加
--show-traceback
长选项。
- -h, --help, --version¶
显示使用摘要或 Sphinx 版本。
Added in version 1.2.
你也可以在源文件和构建目录之后的命令行上给出一个或多个文件名。Sphinx 将只尝试构建这些输出文件(及其依赖项)。
环境变量¶
sphinx-build 引用以下环境变量:
- MAKE
make 命令的路径。也允许使用命令名称。sphinx-build 使用它在 make 模式下调用子构建过程。
Makefile 选项
Makefile
和 make.bat
文件通常由 sphinx-quickstart 创建,并且通常只使用 -b
和 -d
选项运行 sphinx-build。然而,它们支持以下变量来自定义行为:
- PAPER
这将设置
latex_elements
的'papersize'
键:例如,PAPER=a4
将其设置为'a4paper'
,PAPER=letter
将其设置为'letterpaper'
。Note
此环境变量的用法在 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。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=
and domake html
(Linux/Mac)set PYTHONWARNINGS=
and domake html
(Windows)modify your Makefile/make.bat and set the environment variable
See also¶
sphinx-quickstart(1)