Sphinx构建

2.3. Sphinx构建#

这里对Sphinx构建生成发布的文档进行说明。

2.3.1. Makefile选项#

Sphinx 项目初始化后会得到 Makefile 构建文件。但首先要明白的是 Makefile 只是一种编译的辅助工具，并不是必需的。使用 Makefile 的主要好处有：

由 sphinx-quickstart 生成的 Makefile 和 make.bat 文件是只使用了 sphinx-build 的 -b 和 -d 参数。然而，它们支持以下的变量（参数）来定制化：

PAPER: latex_paper_size 的值。
SPHINXBUILD: 替代 sphinx-build 的命令。
BUILDDIR: 指定生成的目录，而不是使用在 sphinx-quickstart 中选择的路径。
SPHINXOPTS: sphinx-build 的附加选项。

2.3.2. sphinx-build 用法#

sphinx-build 是一个脚本，也是一个命令，它才是构建了一个Sphinx文档集的关键。

一般情况下可以借助 Make 系统进行文档构建，但可以编写自己的脚本直接使用 sphinx-build 工具实现更加灵活的应用。

备注

这种情况同样可以借助于 Make 系统。将不同的构建参数写到不同的 Makefile 中，运行 make 命令时通过 -f 参数指定要使用的 Makefile 。

用法如下:

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

在这里，sourcedir 是指源目录，builddir 是指你想指定的生成文档的目录。大部分时候，是不需要指定 filenames。

sphinx-build 脚本有如下的选项:

-b buildername ：最重要的选项: 它选择生成器。常见的生成器如下：

html: 生成HTML页面。这是默认生成器。
dirhtml: 生成HTML页面，但是每个文件单独一个目录。如果web服务器提供服务，能够生成漂亮的URLs(没有 .html 后缀)。
singlehtml: 整个内容生成一个HTML页面。
htmlhelp, qthelp, devhelp, epub: 生成HTML文件，包含了生成上述格式的文档集合的其他信息。
latex: 生成可以被编译成PDF文件的LaTeX源文件通过使用 pdflatex。
man: 生成UNIX操作系统的groff格式的手册。
texinfo: 生成Texinfo文件，它能够通过 makeinfo 处理成 Info 文件。
text: 生成纯文本文件。
gettext: 生成gettext的风格的消息目录（.pot 后缀的文件）。
doctest: 如果 doctest 激活，执行文件中所有的doctests。
linkcheck: 检查所有的外部链接的完整性。

请参看 Available builders，里面列出了Sphinx自身附带的所有的生成器。用户可以添加自己的生成器扩展。

选项介绍

-a: 如果给定，总是生成所有输出文件。默认是只生成新的和更改的源文件的输出文件。（这可能并不适用于所有的生成器。）
-E: 不要使用已保存的环境（系统缓存所有交叉引用），会完全重新生成。默认是仅仅读取和解析自上次运行后新的或者已更新的源文件。
-t tag: 定义标签 tag。这跟 only 指令（标识符）关系密切，如果设置标签就会只包含 only 指令（标识符）的内容。
-d path: 因为Sphinx在生成输出文件之前，必须读取和解析所有的源文件，被解析过的源文件会被缓存为”doctree pickles”。通常，这些缓存文件会被放入于生成目录中的名为 .doctrees 的文件夹里；使用该选项可以选择不同的缓存文件夹（所有生成器都可以共享doctrees文件夹）。
-c path: 使用给定的配置文件目录，忽略源文件中的 conf.py 配置文件。值得注意的是配置文件中的其他文件以及路径可能会跟配置文件目录有关，所以也必须使用指定的路径。
-C: 不使用配置文件；使用 -D 选项后的配置值。

-D setting=value: 覆盖配置文件 conf.py 中一个配置值对。该值必须是一个字符串或者字典值。对于字典值，需要给吃键值对类似：-D latex_elements.docclass=scrartcl。对于布尔值，使用 0 或者 1。
-A name=value: 在HTML模版中，把 value 赋给 name 。

-n: 运行在严格模式。目前，这会对所有丢失的引用抛出警告。
-N: 禁止带颜色的输出。（Windows下任何的带颜色的输出都是无效的。）
-q: 不要在标准输出上输出任何东西，只给出标准错误的警告和错误。
-Q: 不要在标准输出上输出任何东西，也包括警告。只有错误被写入标准错误。
-w file: 输出除标准错误外的警告（和错误）到指定的文件。
-W: 把警告转换成错误输出。这就说构建会在第一个警告的时候停止，sphinx-build 会以错误状态1退出。
-P: （仅调试时有用。）构建时候，如果出现未处理的遗产，运行python调试器，pdb。

在命令行中，你可以在源目录以及生成目录后给出一个或者多个文件名。Sphinx 将会尝试构建给出的这些文件的输出（以及它们的依赖。）

2.3.3. 调用sphinx-apidoc#

sphinx-apidoc 能够对一个python包生成完全的自动的API文档。调用它像这样:

$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]

packagedir 是指生成文档的包所在的路径， outputdir 生成的文档所存放的路径。任何给定的 pathnames 是在生成过程中需要忽略的路径名（[pathnames]里的东西在生成文档中是忽略的。）

sphinx-apidoc 有如下些选项:

-o outputdir: 给出生成的文档所在的路径。
-f, --force: 通常，sphinx-apidoc不会重新生成任何文件。使用这个选项强制重新生成所有的文件。
-n, --dry-run: 使用这个选项的话，不会有任何文件生成。（空运行，或者称为干运行。）
-s suffix: 这个选项指定了输出的文件的文件名后缀。默认情况下，后缀是 rst。
-d maxdepth: 如果存在内容表，设置内容表的最大深度。
-T, --no-toc: 这可以防止生成的表的内容文件 modules.rst。但是当 --full 给出的时候，本选项就不起作用了。
-F, --full: 此选项使得sphinx-apidoc创建一个完整的Sphinx项目，与 sphinx-quickstart 使用同样的机制。大部分的配置值是设置成默认的值，但是你可以通过如下选项修改一些重要的配置值。
-H project: 设置项目名称，使得生成到输出的文件 (请见 project).
-A author: 设置作者名，使得生成到输出的文件 (请见 copyright).
-V version: 设置项目版本，使得生成到输出的文件 (请见 version).
-R release: 设置项目发布，使得生成到输出的文件 (请见 release).

2.3.4. 生成不同格式的文档#

生成html静态网站文件#

进入Sphinx工程根目录, 直接终端运行： make html 即可在 build/html 目录中看到生成的静态网站文件, 双击首页html文件即可打开浏览.

参见

如果文档含有中文, 且需要中文搜索功能, 请参考中文分词问题 .

生成epub文档#

进入Sphinx工程根目录, 直接终端运行： make epub 即可在 build/epub 目录中看到生成的epub文件.

参见

如果文档含有中文, 且需要中文搜索功能, 请参考中文分词问题

生成LaTex文档#

要生成LaTex文档, 需要安装LaTex编译环境, 这里建议使用 TeXLive , 安装包约2GB, 虽然安装后约占4GB空间, 但最为完整且支持Windows、Linux、Mac系统.

安装完成后, 进入Sphinx工程根目录, 在终端输入： make latex 即可生成对应的LaTex文件, 在目录 build/latex 里.

参见

如果文档含有中文, 请参考中文文档问题

这里还可以自定义 Latex 输出样式, 具体参见 LaTeX customization . 主要修改 conf.py 文件, 本人采用的配置如下:

代码 2.3.1 latex_elements of conf.py#

# -- Options for LaTeX output ---------------------------------------------
latex_engine = 'xelatex'
latex_elements = {
'passoptionstopackages': r'''\PassOptionsToPackage{svgnames}{xcolor}''',
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
'papersize': 'a4paper',

# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#'preamble': '',


# Latex figure (float) alignment
'figure_align': 'htbp',


'sphinxsetup': r'''
verbatimwithframe = true,
VerbatimColor = {named}{Gainsboro}, % background colour for code-blocks
VerbatimBorderColor = {rgb}{0.5,0.3,0.9}, % The frame color
VerbatimHighlightColor = {rgb}{0.878,1,1}, % The color for highlighted lines.
InnerLinkColor = {rgb}{0.208,0.374,0.486}, % Inner Link Color
OuterLinkColor = {named}{LightSkyBlue}, % Inner Link Color
TitleColor = {named}{Black},
hintBorderColor = {named}{Green},
dangerBorderColor = {named}{Red},
dangerBgColor = {named}{Tomato},
errorBorderColor = {named}{Crimson},
warningBorderColor = {named}{Chocolate},
attentionborder = 2pt,
attentionBorderColor = {named}{Salmon},
attentionBgColor = {named}{LightSalmon},
noteborder = 2pt,
noteBorderColor = {named}{Goldenrod},
importantborder = 2pt,
importantBorderColor = {named}{OrangeRed},
cautionborder = 2pt,
cautionBorderColor = {named}{Pink},
cautionBgColor = {named}{LightPink}''',

# Using Package for ZH
'preamble':r'''\usepackage{ctex}
\usepackage{bm}
''',
}

提示

上述代码中包含的颜色信息, 可以从 svgnames Colors 找到.

生成PDF文档#

由于Sphinx通过Latex间接生成PDF文档, 所以需要安装LaTex编译环境。安装完成后, 进入Sphinx工程根目录, 直接终端运行： make latexpdf 即可在 build/latex 目录中看到生成的PDF文件.

其实，我们还可以先通过 make latex 生成 tex 文件，然后就可以像处理普通 tex 文件那样自由编辑编译生成PDF文件。

参见

如果文档含有中文, 请参考中文文档问题 , 如果你觉得生成的PDF不好看, 可以参考生成LaTex文档自定义.

自定义生成的PDF文件部分环境预览如下