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

对于布尔值,使用 01 作为值。

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 长选项。

-P, --pdb

(仅用于调试。) 在构建过程中发生未处理异常时运行 Python 调试器 pdb

Changed in version 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 命令的路径。也允许使用命令名称。sphinx-build 使用它在 make 模式下调用子构建过程。

Makefile 选项

Makefilemake.bat 文件通常由 sphinx-quickstart 创建,并且通常只使用 -b-d 选项运行 sphinx-build。然而,它们支持以下变量来自定义行为:

PAPER

这将设置 latex_elements'papersize' 键:例如,PAPER=a4 将其设置为 'a4paper'PAPER=letter 将其设置为 'letterpaper'

Note

此环境变量的用法在 Sphinx 1.5 中被破坏,因为 a4letter 最终作为 LaTeX 文档的选项,而不是所需的 a4paperletterpaper。在 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 do make html (Linux/Mac)

  • set PYTHONWARNINGS= and do make html (Windows)

  • modify your Makefile/make.bat and set the environment variable

See also

sphinx-quickstart(1)