sphinx-build

概要

sphinx-build [options] <sourcedir> <outputdir> [filenames …]

说明

sphinx-build 从“<sourcedir>” 中的文件生成文档, 并将其放在 “<outputdir>”中。

sphinx-build 查找“<sourcedir>/conf.py”作为配置设置。 sphinx-quickstart(1) 可以用来生成模板文件，包括“conf.py”。

sphinx-build can create documentation in different formats. A format is selected by specifying the builder name on the command line; it defaults to HTML. Builders can also perform other tasks related to documentation processing. For a list of available builders, refer to 生成器.

默认情况下，所有过时的东西都会被生成。选定文件的输出只能通过指定单个文件名来生成。

选项

-M buildername

Select a builder, using the make-mode. See 生成器 for a list of all of Sphinx’s built-in builders. Extensions can add their own builders.

重要

Sphinx only recognizes the -M option if it is used first, along with the source and output directories, before any other options are passed. For example:

sphinx-build -M html ./source ./build -W --keep-going

The make-mode provides the same build functionality as a default Makefile or Make.bat, and provides the following additional build pipelines:

latexpdf

生成 LaTeX 文件并通过:program:pdflatex`或 :confval:`latex_engine 设置运行。如果:confval:language 设置为“’ja’”，将自动使用 platex/dvipdfmx latex来生成PDF通道道。

info

生成 Texinfo 文件并通过:program:`makeinfo`运行它们。

备注

The default output directory locations when using make-mode differ from the defaults when using -b.

• doctrees are saved to <outputdir>/doctrees

• output files are saved to <outputdir>/<builder name>

Added in version 1.2.1.

-b buildername, --builder buildername

Selects a builder.

See 生成器 for a list of all of Sphinx’s built-in builders. Extensions can add their own builders.

在 7.3 版本发生变更: Add --builder long option.

-a, --write-all

如果给定，则始终写入所有输出文件。默认情况下，只为新的和更改的源文件写入输出文件。（这可能并不适用于所有生成器。）

备注

This option does not re-read source files. To read and re-process every file, use --fresh-env instead.

在 7.3 版本发生变更: Add --write-all long option.

-E, --fresh-env

不使用已保存的 :term:`运行环境`（其中缓存了交叉引用列表），每次都要重新生成。默认是只读取和处理新的或者上次运行之后有改动的文件。

在 7.3 版本发生变更: Add --fresh-env long option.

-t tag, --tag tag

定义指定的 tag 标签。这与以下内容相关 only 指令，如果设置了此标记，则仅包含其内容。

Added in version 0.6.

在 7.3 版本发生变更: Add --tag long option.

-d path, --doctree-dir path

由于Sphinx必须先读取并解析所有源文件才能编写输出文件，因此解析后的源文件将缓存为 “doctree pickles”。通常，这些文件放在生成目录下名为 :file:`.doctrees`的目录中；使用此选项，您可以选择不同的缓存目录（可以在所有构建器之间共享doctree）。

在 7.3 版本发生变更: Add --doctree-dir long option.

-j N, --jobs N

Distribute the build over N processes in parallel, to make building on multiprocessor machines more effective. Note that not all parts and not all builders of Sphinx can be parallelized. If auto argument is given, Sphinx uses the number of CPUs as N. Defaults to 1.

Added in version 1.2: 这是一个“实验性”功能。

在 1.7 版本发生变更: 支持“auto”的论点。

在 6.2 版本发生变更: Add --jobs long option.

-c path, --config-dir path

不要在源目录中查找:file:conf.py，而是使用给定的配置目录。请注意，配置值给出的各种其他文件和路径预期是相对于配置目录的，因此它们也必须出现在这个位置。

Added in version 0.3.

在 7.3 版本发生变更: Add --config-dir long option.

-C, --isolated

Don’t look for a configuration file; only take options via the --define option.

Added in version 0.5.

在 7.3 版本发生变更: Add --isolated long option.

-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 版本发生变更: Add --define long option.

-A name=value, --html-define name=value

在 HTML 模板中，为变量 name 指定值 value。

Added in version 0.5.

在 7.3 版本发生变更: Add --html-define long option.

-n, --nitpicky

运行 nit-picky 模式。目前来说，就是对每个缺少的引用给出警告。使用配置 nitpick_ignore，可以把某些引用标为“已知缺失”。

在 7.3 版本发生变更: Add --nitpicky long option.

-N, --no-color

不使用彩色输出。

在 1.6 版本发生变更: Add --no-color long option.

--color

Emit colored output. Auto-detected by default.

Added in version 1.6.

-v, --verbose

Increase verbosity (log-level). This option can be given up to three times to get more debug logging output. It implies -T.

Added in version 1.2.

在 7.3 版本发生变更: Add --verbose long option.

-q, --quiet

不要在标准输出上输出任何内容，只将警告和错误写入标准错误。

在 7.3 版本发生变更: Add --quiet long option.

-Q, --silent

不要在标准输出上输出任何内容，也不输出警告，只把错误写到标准错误输出。

在 7.3 版本发生变更: Add --silent long option.

-w file, --warning-file file

除标准错误外，还将警告（和错误）写入给定文件。

在 7.3 版本发生变更: ANSI control sequences are stripped when writing to file.

在 7.3 版本发生变更: Add --warning-file long option.

-W, --fail-on-warning

将警告变为错误。这意味着在第一次警告时停止生成，sphinx-build 退出，且退出状态为1.

在 7.3 版本发生变更: Add --fail-on-warning long option.

--keep-going

使用-W选项，在构建结束时收到警告时继续处理，并且退出状态1，退出 sphinx-build。

Added in version 1.8.

-T, --show-traceback

遇到未处理的异常时，显示完整的跟踪记录（traceback）。否则只显示一个简要的说明，详细的跟踪记录保存为文件以供后续分析。

Added in version 1.2.

在 7.3 版本发生变更: Add --show-traceback long option.

-P, --pdb

（仅供调试使用。）如果生成过程中遇到未处理的异常，运行 Python 调试器 pdb。

在 7.3 版本发生变更: Add --pdb long option.

-h, --help, --version

显示使用方法简要，或 Sphinx 版本。

Added in version 1.2.

您还可以在源和生成目录之后的命令行上提供一个或多个文件名，Sphinx将尝试仅生成这些输出文件（及其依赖项）。

环境变量

The sphinx-build refers following environment variables:

MAKE

制作命令的路径，同时允许使用命令名称。:program:`sphinx-build`使用它来调用make-mode上的子生成过程.

Makefile选项

由 sphinx-quickstart 创建的 Makefile 和 make.bat 文件，调用 sphinx-build 时，通常只有 -b 和 -d 两个选项。不过它们也支持如下变量来定制他们的操作：

PAPER

这设置了“’纸张大小’”键:confval:latex_elements：即“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

附加选项:program:sphinx-build。这些选项也可以通过快捷变量**O**（大写’o’）来设置。

NO_COLOR

When set (regardless of value), sphinx-build will not use color in terminal output. NO_COLOR takes precedence over FORCE_COLOR. See no-color.org for other libraries supporting this community standard.

Added in version 4.5.0.

FORCE_COLOR

When set (regardless of value), sphinx-build will use color in terminal output. NO_COLOR takes precedence over 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 系统）

• 修改 Makefilie 和/或 make.bat 文件，设置其中的环境变量

另请参阅

sphinx-quickstart(1)