使用 sphinx-build

sphinx-build 脚本用以进行 Sphinx 文档的构筑. 如下使用:

$ sphinx-build [options] sourcedir builddir [filenames]

sourcedir 指向 source directory, 而 builddir 是指构筑出的文档你想放置的目标路径. 多数情况,你用不到 filenames.

sphinx-build 脚本支持一系列参数:

-b buildername

其中最重要的是: 指明使用什么构筑器. 常见的有:

html

构筑为 HTML 页面,这是默认构筑器.

dirhtml

构筑为 HTML 页面,不过输出到单一目录中,并为web发布制作为美化URL(不是 .html).

singlehtml

构筑为包含所有内容的单页HTML .

htmlhelp, qthelp, devhelp, epub

构筑为HTML 文件,并配合附加信息,打包成以上格式中指定的一种.

latex

构筑为 LaTeX 源码,以便使用 pdflatex 编译成 PDF 文档.

man

构筑为手册页面,使用UNIX系统中的 groff 格式.

text

构筑为纯文本文件.

gettext

构筑为 gettext-style 消息索引 (.pot 文档).

doctest

如果 doctest 扩展已激活,执行所有文档中的 doctests .

linkcheck

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

参考 Available builders 列出所有Sphinx 内置的构筑器. 扩展可以拥有自个儿的构筑器.

-a

一但设置,总是输出所有文件. 默认是只输出有更新的. (这一选项不是所有构筑器都支持)

-E

不使用保存的 environment (缓存了所有交叉索引),而是重建一切. 默认是只读取和处置相对前次构筑有变化的文件.

-t tag

定义标签 tag. 这是有关 only 指令的, 将仅处理指定标签目录中的内容.

New in version 0.6.

-d path

因为 Sphinx 在输出前将尽力读取和处理所有源文件, 处理中的源文件将缓存在 “doctree pickles”,通常会在构筑目录的 .doctrees 文件夹里. 这个参数可以由你选择缓存目录( .doctrees 文件夹可以为所有构筑器共享)

-c path

不用到源文件目录找 conf.py , 使用指定的配置文件. 注意在配置文件中提及的路径都是相对配置文件所在目录的, 所以,他们也应该在同一路径中.

New in version 0.3.

-C

不寻找配置文件,使用参数 -D 给出的.

New in version 0.5.

-D setting=value

覆盖配置文件 conf.py 中的设置. 该设置必须是一个字符串或字典值. 对于后者,可以这样来设置键值: - D latex_elements.docclass= scrartcl 对于布尔值用 0 或 1 .

Changed in version 0.6: 现在可以使用字典值了.

-A name=value

对HTML 模板中的 name 绑定 value .

New in version 0.5.

-n

以挑剔模式运行.目前,这将产生所有引用丢失的警告.

-N

不要产生颜色输出 (在Windows,这不是个选项,因为根本没有)

-q

不要输出任何信息.仅将报警和错误输出到标准错误.

-Q

不要输出任何信息,包括控制警报.仅将报警和错误输出到标准错误.

-w file

将警告(和错误)写入给定的文件,代替标准错误的输出.

-W

将警告变为错误,这意味着只要遇到警告就会终止构筑, sphinx-build 的退出状态将是 1.

-P

(仅在调试时有用) 在构筑文档时,发生未处理的异常就运行Python 调试器, pdb

你也可以在命令行中给定一个或多个文件名,以及构筑目录, Sphinx 将尝试只对给出的文件(以及它们依赖的)进行构筑.

Makefile 配置

Makefile 和 make.bat 是由 sphinx-quickstart 创建的, 通常我们使用只有 -b 和 -d 选项的 program:sphinx-build 来完成文档构筑. 然而,他们支持以下自定义行为的选项:

PAPER

配置项 latex_paper_size 的值

SPHINXBUILD

替代 sphinx-build 的命令

BUILDDIR

替代在 sphinx-quickstart 中指定的构筑目录.

SPHINXOPTS

sphinx-build 的附加选项.