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.构建者还可以执行与文档处理相关的其他任务.

默认情况下, 构建过时的所有内容.只能通过指定单个文件名来构建所选文件的输出.

有关可用选项的列表, 请参阅 sphinx-build -b.

选项

-b buildername

最重要的选项:它选择一个构建器.最常见的建筑商是:

html

构建HTML页面.这是默认构建器.

dirhtml

构建HTML页面, 但每个文档只有一个目录.如果从网络服务器提供, 则可以获得更漂亮的URL(没有 .html).

singlehtml

使用整个内容构建单个HTML.

htmlhelp, qthelp, devhelp, epub

使用其他信息构建HTML文件, 以便以这些格式之一构建文档集合.

applehelp

构建Apple帮助手册.需要 hiutil 和 codesign, 它们不是开源的, 目前仅适用于Mac OS X 10.6及更高版本.

latex

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

man

为UNIX系统构建groff格式的手册页.

texinfo

使用 makeinfo 构建可以处理为Info文件的Texinfo文件.

text

构建纯文本文件.

gettext

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

doctest

如果启用了 doctest 扩展名, 则运行文档中的所有doctests.

linkcheck

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

xml

构建Docutils原生XML文件.

pseudoxml

构建紧凑的漂亮打印的 “pseudo-XML” 文件, 显示中间文档树的内部结构.

请参阅 构建器 以获取Sphinx附带的所有构建器的列表.扩展可以添加自己的构建器.

-M buildername

替代 -b.使用Sphinx make_mode 模块, 它提供与默认相同的构建功能 Makefile或Make.bat.除了所有Sphinx 构建器 之外, 还提供以下构建管道:

latexpdf

构建LaTeX文件并运行它们 pdflatex, 或者按照 latex_engine 设置.如果 language 设置为``’ja’``, 将自动使用 platex/dvipdfmx latex到PDF管道.

信息

构建Texinfo文件并运行它们 makeinfo.

重要

如果首先放置, Sphinx只识别 -M 选项.

1.2.1 新版功能.

-a

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

-E

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

-t tag

定义标签*标签*.这与以下内容相关 only 指令, 如果设置了此标记, 则仅包含其内容.

0.6 新版功能.

-d path

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

-j N

并行地在 N 进程上分配构建, 以使在多处理器机器上构建更有效.请注意, 并非Sphinx的所有部件而非所有构建器都可以并行化.如果给出 auto 参数, Sphinx将CPU的数量用作 N.

1.2 新版功能: 该选项应被视为 experimental.

在 1.7 版更改: Support auto argument.

-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.

对于布尔值, 使用 0 或 1 作为值.

在 0.6 版更改: 该值现在可以是字典值.

在 1.3 版更改: 该值现在也可以是列表值.

-A name=value

将 name 分配给HTML模板中的 value.

0.5 新版功能.

-n

以挑剔模式运行.目前, 这会为所有缺少的引用生成警告.请参阅配置值 nitpick_ignore 以获取将某些引用排除为 “known missing” 的方法.

-N

不要发出彩色输出.

-v

增加详细程度(loglevel).此选项最多可以提供三次以获得更多调试日志记录输出.它意味着:选项: -T.

1.2 新版功能.

-q

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

-Q

不要在标准输出上输出任何内容, 也要禁止警告.只有错误写入标准错误.

-w file

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

-W

将警告变为错误.这意味着构建在第一次警告时停止, 并且 sphinx-build 退出并退出状态为1.

--keep-going

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

1.8 新版功能.

-T

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

1.2 新版功能.

-P

(仅用于调试.)如果在构建时发生未处理的异常, 则运行Python调试器:mod:pdb.

-h, --help, --version

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

1.2 新版功能.

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

环境变量

:程序:`sphinx-build`指的是以下环境变量:

MAKE

制作命令的路径.还允许使用命令名称. sphinx-build 使用它来调用make-mode上的子构建过程.

Makefile选项

Makefile 和 make.bat 文件由 sphinx-quickstart 创建通常运行 sphinx-build 只能使用 -b 和 :option :-d 选项.但是, 它们支持以下变量来自定义行为:

PAPER

这设置了 'papersize' 键 latex_elements: 即 PAPER = a4 将它设置为 'a4paper' 并将 PAPER = letter 设置为 'letterpaper “.

注解

这个环境变量的使用在Sphinx 1.5中被打破, 因为 a4 或 letter 最终作为LaTeX文档的选项而不是所需的 a4paper, 分别为. letterpaper.固定在1.7.7.

SPHINXBUILD

使用的命令代替 sphinx-build.

BUILDDIR

要使用的构建目录而不是在 sphinx-quickstart 中选择的目录.

SPHINXOPTS

其他选项 sphinx-build.

弃用警告

如果在构建用户文档时显示任何弃用警告, 如 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)