狮身人面像--构建

提纲

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

描述

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

sphinx-build 寻找 <sourcedir>/conf.py 用于配置设置。 sphinx-quickstart(1) 可用于生成模板文件,包括 conf.py

sphinx-build 可以创建不同格式的文档。通过在命令行上指定构建器名称来选择一种格式;它缺省为HTML。构建器还可以执行与文档处理相关的其他任务。有关可用构建器的列表,请参阅 sphinx-build -b

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

选项

-b buildername

最重要的选项是:它选择一个建造者。最常见的建筑商有:

html

构建HTML页。这是默认的构建器。

dirhtml

构建HTML页面,但每个文档只有一个目录。使URL更漂亮(否 .html )如果是从网络服务器提供的。

singlehtml

构建包含整个内容的单个HTML。

htmlhelpqthelpdevhelpepub

使用附加信息生成HTML文件,以便以这些格式之一生成文档集合。

applehelp

创建一本苹果帮助书。要求 hiutilcodesign ,它们不是开源的,目前只在Mac OS X 10.6和更高版本上可用。

latex

构建可编译为PDF文档的LaTeX源代码,使用 pdflatex

man

为Unix系统构建Groff格式的手册页。

texinfo

使用构建可处理为Info文件的纹理信息文件 makeinfo

text

构建纯文本文件。

gettext

构建getText样式的消息目录 (.pot 文件)。

doctest

运行文档中的所有文档测试,如果 doctest 扩展已启用。

linkcheck

检查所有外部链接的完整性。

xml

构建Docutils-原生XML文件。

pseudoxml

构建紧凑、打印精美的“伪XML”文件,显示中间文档树的内部结构。

看见 建筑商 查看Sphinx随附的所有建造者的列表。扩展可以添加自己的构建器。

-M buildername

替代 -b 。使用狮身人面像 make_mode 模块,它提供与默认生成功能相同的生成功能 Makefile or Make.bat 。除了所有的狮身人面像 建筑商 ,可以使用以下构建管道:

latexpdf

构建LaTeX文件并运行它们 pdflatex ,或按 latex_engine 布景。如果 language 设置为 'ja' ,将自动使用 platex/dvipdfmx LaTeX到PDF的管道。

info

构建纹理信息文件并运行它们 makeinfo

重要

狮身人面像只识别 -M 选项(如果它被放在第一位)。

在 1.2.1 版本加入.

-a

如果给定,则始终写入所有输出文件。默认情况下,仅写入新的和更改的源文件的输出文件。(这可能不适用于所有建筑商。)

-E

不要使用已保存的 environment (缓存所有交叉引用的结构),但完全重建它。默认情况下,仅读取和分析自上次运行以来新的或已更改的源文件。

-t tag

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

在 0.6 版本加入.

-d path

由于Sphinx必须读取并解析所有源文件,然后才能写入输出文件,因此解析后的源文件将被缓存为“Doctree Pickle”。通常,这些文件放在一个名为 .doctrees 在构建目录下;使用此选项,您可以选择不同的缓存目录(文档树可以在所有构建器之间共享)。

-j N, --jobs N

将构建分发到以下位置 N 并行进程,以使在多处理器计算机上构建更加有效。请注意,不是Sphinx的所有部分和构建器都可以并行化。如果 auto 参数的情况下,Sphinx使用CPU数量作为 N

在 1.2 版本加入: 应考虑此选项 experimental

在 1.7 版本发生变更: 支持 auto 争论。

在 6.2 版本发生变更: 增列 --jobs 长时间的选择。

-c path

别去找那些 conf.py 在源目录中,但改用给定的配置目录。请注意,由配置值提供的各种其他文件和路径预计都是相对于配置目录的,因此它们也必须位于此位置。

在 0.3 版本加入.

-C

不要寻找配置文件;只需通过 -D 选择。

在 0.5 版本加入.

-D setting=value

中设置的配置值。 conf.py 文件。该值必须是数字、字符串、列表或字典值。

对于列表,您可以使用逗号分隔元素,如下所示: -D html_theme_path=path1,path2

对于字典值,提供设置名称和键,如下所示: -D latex_elements.docclass=scrartcl

对于布尔值,请使用 01 就像价值一样。

在 0.6 版本发生变更: 该值现在可以是一个字典值。

在 1.3 版本发生变更: 该值现在也可以是列表值。

-A name=value

使之成为 name 分配给 value 在HTML模板中。

在 0.5 版本加入.

-n

在挑剔的模式下运行。目前,这会为所有缺少的引用生成警告。查看配置值 nitpick_ignore 寻找一种方法来排除某些引用,如“已知的丢失”。

-N, --no-color

不要发射彩色输出。

在 1.6 版本发生变更: 增列 --no-color 长时间的选择。

--color

发射彩色输出。默认情况下自动检测。

在 1.6 版本加入.

-v

增加详细程度(日志级别)。此选项最多可以提供三次,以获得更多的调试日志记录输出。它暗示着 -T

在 1.2 版本加入.

-q

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

-Q

不要在标准输出上输出任何内容,也不要显示警告。只有错误才会写入标准错误。

-w file

除标准错误外,还向给定文件写入警告(和错误)。

-W

把警告变成错误。这意味着生成在出现第一个警告时停止,并且 sphinx-build 退出,退出状态为1。

--keep-going

使用-W选项,在生成结束时收到警告时继续进行处理,并且 sphinx-build 退出,退出状态为1。

在 1.8 版本加入.

-T

当发生未处理的异常时显示完整的回溯。否则,将仅显示摘要,并将回溯信息保存到文件中以供进一步分析。

在 1.2 版本加入.

-P

(仅适用于调试。)运行Python调试器, pdb 如果在生成过程中发生未处理的异常,则返回。

-h, --help, --version

显示使用情况摘要或Sphinx版本。

在 1.2 版本加入.

您还可以在命令行中的源代码和构建目录之后指定一个或多个文件名。然后,Sphinx将尝试仅构建这些输出文件(及其依赖项)。

环境变量

这个 sphinx-build 指的是以下环境变量:

MAKE

一条下达命令的路径。命令名也是允许的。 sphinx-build 使用它在生成模式上调用子生成过程。

生成文件选项

这个 Makefilemake.bat 文件创建者 sphinx-quickstart 通常跑步 sphinx-build 仅限使用 -b-d 选择。但是,它们支持以下变量以自定义行为:

PAPER

这将设置 'papersize' 的关键字 latex_elements :即 PAPER=a4 将其设置为 'a4paper'PAPER=letter'letterpaper'

备注

在Sphinx 1.5中,此环境变量的用法被破坏,因为 a4letter 最终成为LaTeX文档的选项,而不是所需的 a4paper ,分别为: letterpaper 。固定在1.7.7。

SPHINXBUILD

要使用的命令而不是 sphinx-build

BUILDDIR

要使用的生成目录,而不是 sphinx-quickstart

SPHINXOPTS

其他选项用于 sphinx-build 。也可以通过快捷方式变量设置这些选项 O (大写‘o’)。

NO_COLOR

设置时(无论值如何), sphinx-build 不会在终端输出中使用颜色。 NO_COLOR takes precedence over FORCE_COLOR. See no-color.org 用于支持此社区标准的其他类库。

在 4.5.0 版本加入.

FORCE_COLOR

设置时(无论值如何), sphinx-build 将在终端输出中使用颜色。 NO_COLOR 优先于 FORCE_COLOR

在 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)