Question

我们在第 7 章中介绍了如何用 Sphinx 写文档，现在来看看如何用 Jenkins 来辅助 Sphinx 编写文档。

用 Sphinx 编写文档时经常会遇到下述问题。

· reST 语法错误

· 忘记提交文档中引用的图片或源码

如果存在上述问题，Sphinx 会在执行构建命令时发出警告。因此，只要我们利用 Jenkins 定期监视文档的构建，就能尽早发现这些问题。

本书就是借助 Sphinx 编写的。接下来我们将以本书的编写过程为例，学习一下我们应该怎样用 Jenkins 管理多人共同执笔的书稿。该方法不仅适用于多人共同管理文档的情况，对单独管理文档的情况也有一定的帮助。

10.7.1　安装 Sphinx

首先将 Sphinx 安装到本地环境中。

$ pip install sphinx

10.7.2　在 Jenkins 添加 Job

该 Job 的设置如下（/var/hg/bpbook 为源码版本库）。

① 基本设置

· Job 类型：自由风格

· Job 名称：bpbook

② 源码管理系统

· SCM：Mercurial

· 版本库：/var/hg/bpbook

· 分支：default

③ 构建触发器

· 种类：定期执行

· 日程表：H/15****（每小时的 15 分）

10.7.3　Sphinx 构建发出警告时令 Job 失败

Sphinx 的 -w 选项可以将警告内容以文件形式输出。我们希望出现警告时让 Jenkins 的 Job 失败，所以要在“Execute shell”选项卡处进行如下设置：当输出警告内容的文件不为空时，用返回码 9 结束执行。

sphinx-build -a -E -w build_warnings.txt source docs
if [ -s build_warnings.txt ] ; then
  exit 9
fi

这里的返回码可以用 0 之外的任意数字。Jenkins 将所有构建完毕时返回码不为 0 的 Job 均视为失败。另外，为保证每次都重新构建所有文档，要加上 -a -E 选项。

10.7.4　查看成果

Jenkins 可以在管理界面查看工作区内的文件，因此我们可以在这里查看 Job 构建的文档（图 10.21）。

图 10.21　查看工作区

Jenkins 中的各 Job 首页的“描述”中允许添加 html 标签，我们可以将已构建的文档的链接插入“描述”中，这样一来就能直接从首页点击链接查看构建后的文档了（图 10.22）。

图 10.22　编辑 Job 首页的“描述”

10.7.5　通过 Task Scanner Plugin 管理 TODO

编写代码和稿件时，我们常需要将一些临时想到的事或暂时不需要做的事以 TODO 注释的形式记录下来。用 Jenkins 的 Task Scanner Plugin 插件可以让我们在报告中看到 TODO 注释（图 10.23）。

图 10.23　Task Scanner Plugin 报告

如图 10.24 所示，报告中还对对应行做了高亮处理。

图 10.24　高亮显示

另外，Sphinx 扩展中有一个 todo 扩展，激活之后即可允许用户使用 todo 指令（图 10.25）。todo 指令的布局与 note 和 warning 相同。

图 10.25　使用 todo 指令的示例

与其他人合著一本书时，我们常会怀疑自己写的内容与其他章节是否存在矛盾，或是自己写的稿子是否满足与合著者之间定下的规则。如果每出现一次这种情况就停下手去检查一遍，势必拖累稿子的进度，所以我们选择先留下 TODO 注释，等待最后统一解决。

另外，TODO 注释经常写了不删，让人搞不清到底问题有没有解决。这种情况不仅存在于写稿的过程中，在敲代码时也同样会发生。虽然每次处理完源码或稿件都手动 grep 搜索 TODO 注释能避免这种情况发生，但实在太麻烦了。

因此，在用 Jenkins 执行测试或构建文档时，可以顺便生成一个 TODO 的列表。另外，Task Scanner Plugin 能够用图表显示 TODO 注释的数量。随着 TODO 被一个个解决，我们能够直观地掌握其减少的过程。看到 TODO 减少能够激发开发者解决 TODO 的积极性，在某种意义上起到提高效率的作用。

10.7.6　Task Scanner Plugin 的设置示例

首先从“管理插件”安装 Task Scanner Plugin。完成后，Job 设置界面的“构建后操作”选项卡处会增加“Scan workspace for open tasks”一项。勾选该项，输入下述几项。

· Files to scan：TODO 的搜索对象

· Files to exclude：这里设置的对象将不包含在搜索范围内

· Tasks tags：这里输入的字符串将被视为 TODO，计入统计结果

管理本书稿的 Job 就是按照图 10.26 设置的。

图 10.26　Task Scanner Plugin 设置示例