Question

本章最开始就列举了下列“让人愿意写文档并能轻松写文档的条件”。

· 能在平时用的编辑器上写文档

· 能把文档分成几个文件来写

· 能用 Mercurial 等轻松实现版本管理

· 能集中精神编辑内容，不用顾虑装饰等外观问题

· API 参考手册与程序的管理一体化

· 平时的引用可通过 Web 浏览器共享

· 在提交文档时可转换成漂亮整齐的单一文件格式

· 写有用的文档

现在我们分条学习如何用 Sphinx 实现这些条件。

7.3.1　由于是纯文本，所以能在平时用的编辑器上写文档

想必程序员都有过读纯文本文档的经历。特别是开源程序的附属文档，其中有许多图表都是由纯文本表达，它们和程序一起被视为源码进行管理。为什么很多人选择用这种方法写文档呢？理由有以下几点。

· 不必借助特殊工具，仅用纯文本就能表达结构或图表

· 编写、阅览文档不依赖特殊工具，无论该工具有偿无偿

· 可以用源码管理工具来管理文本文件的变更

· 写代码和写文档都能在惯用的编辑器上进行

可见，用纯文本写文档并不是心血来潮，它是有明确优势的。

Sphinx 就是用纯文本写文档。用户按照特定的规则描述纯文本，然后 Sphinx 来解释该规则，将文本以 HTML、PDF 等格式输出，这就是 Sphinx 的作用。

图片要以独立文件的形式统一保存，跟文档的文本文件放在同一目录或其子目录中（LIST 7.11）。这样，一旦日后遇到容量等问题需要改变大小或格式时，能方便地统一转换。

LIST 7.11　用于植入图片的 figure 指令

方便多人同时编辑，也便于用版本管理工具进行管理
.. figure:: images/7-sphinx-vcs-manage.png
   用 Mercurial 管理 Sphinx 文档

7.3.2　 信息与视图相分离，所以能集中精神编辑内容，不用顾虑装饰等外观问题

Sphinx 的以下特征实现了信息（ Data）与视图（ View）的分离，所以我们能集中精神写文档。

· 用 reStructuredText 写文档看不到最终的显示效果

· 可以集中精力描述逻辑结构化的正文

· 最终的设计由 Sphinx（或者由制定主题的设计师）调整

· 相当于其他文档编辑工具的大纲功能

前面我们学习了如何用 reStructuredText 写文档以及如何用 Sphinx 构建并输出。总而言之，我们可以把装饰和外观交给 Sphinx 处理，自己集中精神写文章内容。

比如，我们要用 Sphinx 编写如下会议记录（LIST 7.12）。

LIST 7.12　会议记录示例

============================
2015/2/17 会议记录
============================
: 参加者: SW 商事平野、BP 清水川、BP 小田切、BP 冈野
: 日期及时间: 2015/2/17（二）10:00 ～ 11:30
: 场地: SW 商事的会议室
今日议程
==================
1. 介绍新成员
2. 面向开发者的程序库的开发情况
3. 11 月起的工作方针
介绍新成员
=================
冈野:
   Python 经验 10 年。平时用 Django 框架和 GoogleAppEngine 进行开发。
   参与了许多面向 Python/Django 的开源程序库的开发，
   其中以面向移动电话的开发支持库 django-bpmobile 为代表。

这篇会议记录是用 reStructuredText 写的。如果用 Sphinx 构建，可以获取如图 7.7 ～图 7.9 所示的经过整理的 HTML 或 PDF 文件。

图 7.7　Sphinx 的 HTML 输出（default 主题）

图 7.8　Sphinx 的 HTML 输出（bizstyle 主题）

图 7.9　Sphinx 的 PDF 输出（latexpdfja）

此外，Sphinx 还搭载了强大的代码高亮功能，它可以给程序代码等自动搭配颜色，提高可读性。

代码高亮功能由 Sphinx 捆绑的 Pygments4 提供。支持的格式方面，编程语言、设置文件、HTML 模板等加起来有 200 种左右，而且仍在增加（图 7.10 ～图 7.12）。

4 http://pygments.org/docs/lexers/

图 7.10　Windows ini 格式的高亮

图 7.11　Python 代码的高亮

图 7.12　Apache conf 格式的高亮

7.3.3　可根据一个源码输出 PDF 等多种格式

前面我们了解了纯文本的好处以及文件分割的好处。不过，我们仍然希望在印刷和交付时，文档能被整合成一个文件。

另外，虽然文本文件形式的文档与 PDF 文档有着同样的信息价值，但文本文件形式的文档总会给人一种廉价感。为避免因此而受到影响，我们在上交文档时最好准备一份经过简单排版和装饰的 PDF 文件。

Sphinx 可以将同一份源码文件转换成多种不同的格式。输出格式支持 HTML、PDF、EPUB、man、LaTeX、HTML Help（chm）等（图 7.13）。另外，导入自制的扩展后，还可以支持一些原本不支持的格式。

图 7.13　Sphinx 输出的 PDF

7.3.4　通过结构化，文档可分成几个文件来写

程序员在写程序时不会将所有代码都写在同一个文件里。因为历史和长期以来的经验告诉我们，这样做是非常不明智的。源码要以概念或目的为单位分割成多个文件，在目录中进行分类管理。

这个做法对于文档同样有效。分割、分类的标准可由写文档的人随意制定，但其中还是有一些技巧可言的。比如 LIST 7.13 这个例子就能让人一眼看出文档的结构，非常清晰。

LIST 7.13　文档目录结构示例

文档/
   +-- index.txt
   +-- 项目管理/
   |  +-- index.txt
   |  +-- project-goal.txt
   |  +-- member-and-structure.txt
   |  +-- phase1-schedule.txt
   +-- 设计/
   |  +-- index.txt
   |  +-- middleware-versions.txt
   |  +-- framework-comparision.txt
   |  +-- server-structures.txt
   |  +-- components-and-interfaces.txt
   +-- 开发/
   |  +-- index.txt
   |  +-- repository.txt
   |  +-- coding-rule.txt
   |  +-- develop-environment.txt
   |  +-- release-packaging.txt
   +-- 参考手册/
   |  +-- index.txt
   |  +-- install-and-setup.txt
   |  +-- class-and-functions.txt
   |  +-- api-references.txt
   +-- 会议记录/
    +-- index.txt
    +-- 20150201-meeting.txt
    +-- 20150208-meeting.txt
    +-- 20150215-meeting.txt

这样分类之后，我们写文档时的注意力就会转移到以下几项上。相较于在单一文件中编写文档，这样能更加轻松地整理文档内容。

· 根据分类或文件名调整该文件涉及内容的范围

· 文件内容或文章量达到一定规模后，重新整理内容、分割文件

· 文件达到一定数量后，将同一分类的文件归入一个子目录

如上面例子所示，Sphinx 可以借助文件分割以及目录分类来构筑文档。这些分割开的文件会在使用 Sphinx 构建时通过链接等方式添加关联，并采用适合 HTML、PDF 等格式的形式输出。

至于输出之后的效果，完全可以交给 HTML 或 PDF 等输出算法来处理。写文档的人只需关心文档结构是否符合逻辑，链接数量是否恰到好处等。也就是说，我们能完全以逻辑思考为中心来编辑文档，不必去想多余的事。

7.3.5　能用 Mercurial 等轻松实现版本管理

Sphinx 的文档由多个目录下的多个纯文本文件共同构成。图片文件也和文本文件一样保存在目录中。在这种结构下，我们能以极细的粒度进行版本管理，而且即便出现多人同时编辑文档的情况，各个变更之间也不会发生冲突（图 7.14）。

图 7.14　用 Mercurial 管理 Sphinx 文档

7.3.6　API 参考手册与程序的管理一体化

作为开发者，我们有时候会自己写 API，有时候又会拿现成的 API 来用。理想的情况是写好 API 的同时就能做好 API 参考手册，但如果是没有人读的东西，做出来也只是白费功夫。所以什么时候该做什么东西，要仔细结合重要性进行考量。

进行 Python 开发时，只要 docstring 用得好，完全可以解决这一问题。docstring 指的是写在 Python 模块、类、函数最开头的字符串对象。比如，我们会用 docstring 在函数的开头像 LIST 7.14 这样描述文档。

LIST 7.14　path.py

# -*- coding: utf-8 -*-
def commonprefix(path_list):
  """
  返回路径的“`path_list`”中最长的公共前缀
  （依次判断路径名的每一个字符）
    >>> commonprefix(['/usr/bin/python', '/usr/local/bin/python'])
    '/usr/'
    >>> commonprefix(['/usr/bin/python'])
    '/usr/bin/python'
  如果“`path_list`”为空，则返回空字符串“''”
    >>> commonprefix([])
    ''
  请注意，由于每次只判断一个字符，
  所以可能返回非法路径
    >>> commonprefix(['/usr/local/bin/python', '/usr/local/bin/pylint'])
    '/usr/local/bin/py'
  """
  if not path_list: return ''
  s1 = min(path_list)
  s2 = max(path_list)
  for i, c in enumerate(s1):
    if c != s2[i]:
      return s1[:i]
  return s1

如 LIST 7.15 所示，以这种方式写进去的函数文档可以在交互模式中引用。

LIST 7.15　函数文档的引用

>>> help(path.commonprefix)
Help on function commonprefix in module path:
commonprefix(path_list):
  返回路径的“`path_list`”中最长的公共前缀
  （依次判断路径名的每一个字符）
    >>> commonprefix(['/usr/bin/python', '/usr/local/bin/python'])
    '/usr/'
    >>> commonprefix(['/usr/bin/python'])
    '/usr/bin/python'
-（中间省略）-

Python 还拥有 doctest 功能，它能够识别出在 docstring 中描述的，也就是和交互模式显示信息相同的部分并进行测试。进行 doctest 的最简单的方法就是执行 LIST 7.16 中的命令。

LIST 7.16　doctest

$ python -m doctest -v path.py
...
4 tests in 2 items.
4 passed and 0 failed.
Test passed.

这样一来，函数文档里写的内容和函数的功能就不会再有偏差了。另外，我们可以放心地将 docstring 植入 Sphinx 文档。植入时要用到 sphinx.ext.autodoc 扩展，具体描述如下（LIST 7.17、LIST 7.18）。

LIST 7.17　conf.py

sys.path.insert(0, '【path.py 所在目录的路径】')
extensions = ['sphinx.ext.autodoc',]

LIST 7.18　path.rst

================
AutoDoc 范例
================
.. autofunction:: path.commonprefix

然后我们就能够得到图 7.15 中的输出结果了。

图 7.15　用 sphinx.ext.autodoc 将 docstring 植入 Sphinx 文档

可见，只要 API 的实现及其相关文档保持在可测试状态，并保证其能自动植入 Sphinx 文档之中，许多问题就迎刃而解了。另外，如测试驱动开发一样，将介绍 API 使用方法的文档兼测试写在实现 API 之前，这既能让人们对该 API 的使用有一个更明确的认识，也能给开发带来帮助。

7.3.7　通过 Web 浏览器共享

文档内常常包含开发规则或 API 参考手册等内容。让成员能在 Web 上浏览到这些信息会带来许多好处。

当我们想和其他开发者共享某个文档，进而展开讨论或交流时，如果能通过 URL 指定该文档，那将让共享变得非常方便。而且这样做不需要在邮件上挂附件，能避免出现多余的文档副本。

Sphinx 用起来最方便的输出格式就是 HTML。我们可以设置一个机制，在 Mercurial 的版本管理之下提交 Sphinx 源码时，用 Jenkins 自动将其构建成 HTML，这样一来就能随时在 Web 上看到最新的文档了。与 Jenkins 的关联我们将在第 10 章中详细了解。

7.3.8　导入 Sphinx 后仍存在的问题

前面我们了解了 Sphinx 作为文档编辑工具的一面，但有些问题并不是导入 Sphinx 就能解决的。另外，对于非程序员或非技术人员来说，Sphinx 的某些优点反而会变成缺点。

所以，我们这里要探讨导入 Sphinx 无法解决的问题以及导入后新增的问题。

◉ 写有用的文档

我们在“让人愿意写文档并能轻松写文档的条件”中提到了“写有用的文档”这一条。可惜的是，仅导入 Sphinx 并不能解决这一问题。在 7.4 节，我们将学习如何写有用的文档。

◉ 审查需要多花心思

许多文字处理软件都配备了审查或审校的功能，但 Sphinx 中并没有这类功能。所以在进行审查校对、反馈校对内容等工作时，需要额外花些心思才行。

Sphinx 中有用来记录 todo 的扩展表示法。使用这个功能前，先要在 conf.py 中作如下设置（LIST 7.19）。

LIST 7.19　conf.py

extensions = ['sphinx.ext.todo',]
todo_include_todos = True

然后像 LIST 7.20 这样在文档中描述审查校对的内容。

LIST 7.20　在 todo 指令中描述校对内容

今日议程
==================
1. 介绍新成员
2. 面向开发者的程序库的开发情况
3. 11 月起的工作方针
.. todo:: （sato） 缺少** 事务联络**，请添加。

如果想获取 todo 的一览表，需要在文档的任意位置加一行 .. todolist:: 然后 make html。

sphinx.ext.todo - Support for todo items

http://www.sphinx-doc.org/en/stable/ext/todo.html

◉ 部分人只会在 WYSIWYG 编辑器上写文档

前面也说了，Sphinx 的信息与视图是分离的，所以我们能集中精力去编写文章，不必为装饰等外观方面的问题分心。但是对于一部分人而言，不能把握输出效果就写不下去文章。这一类人会觉得没有 WYSIWYG 编辑器的 Sphinx 很难用。这个问题暂时还没有很好的解决方法。

◉ 输出 PDF 需要搭建相应的环境

虽然 Sphinx 支持多种输出格式，但仅有它本身时，是不能输出 PDF 的。输出 PDF 有两种方法（经由 LaTeX 和使用 reportlab 扩展）。这两种方法各有特点，其中经由 LaTeX 的输出更加直观。

关于用 Sphinx 输出 PDF 的方法，http://www.sphinx-doc.org/en/stable/index.html 网站上介绍了相关的导入流程以及使用方法。此外，该网站上还介绍了将 Sphinx 文档经由 LaTeX 输出成 PDF 的方法。

用 Sphinx 生成 PDF 文件

http://www.sphinx-doc.org/en/stable/tutorial.html?highlight=pdf