3.2　Sphinx模块

Sphinx是高度可扩展的：它的基本功能只支持手工文档，但它有许多有用的模块可以支持自动化文档和其他功能。例如，sphinx.ext.autodoc可以从模块中抽取rest格式的文档字符串（docstrings）并生成.rst文件。sphinx-quickstart在运行的时候会问你是否想激活某个模块，也可以编辑conf.py文件并将其作为一个扩展。

extensions = ['sphinx.ext.autodoc']

值得注意的是，autodo``c不会自动识别并包含模块，而是需要显式地指明需要对哪些模块生成文档，类似下面这样：

广告：个人专属 VPN，独立 IP，无限流量，多机房切换，还可以屏蔽广告和恶意软件，每月最低仅 5 美元

.. automodule:: foobar
　 :members: ①
　 :undoc-members: ②
　 :show-inheritance: ③

① 要求输出所有已加文档的成员信息（可选）。

② 要求输出所有未加文档的成员信息（可选）。

③ 显示继承关系（可选）。

同时要注意以下几点。

 
  • 如果不包含任何指令，Sphinx不输出任何内容。
  • 如果只指定:members:，那么在模块／类／方法这一树状序列中未加文档的节点将被忽略，即使其成员是加了文档的。例如，如果给一个类的所有方法都加了文档，但这个类没有加文档，:members:除这个类及其方法。为了避免这种情况，要么必须为该类加上一个文档字符串，要么同时指定 :undoc-members:。
  • 模块需要在Python可以导入的位置。通过添加.、..和/或../..到sys.path中会对此有帮助。

autodoc可以将实际源代码中的大部分文档都包含进来，甚至还可以单独挑选某个模块或方法生成文档，而不是一个“非此即彼”的解决方案。通过直接关联源代码来维护文档，可以很容易地保证文档始终是最新的。

如果你正在开发一个Python库，那么通常需要以表格的形式来格式化你的API文档，表格中包含到各个模块的独立的文档页面的链接。sphinx.ext.autogen模块就是用来专门处理这一常见需求的。首先，需要在conf.py中启动它：

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']

现在就可以在一个.rst中加入类似下面的内容来自动为特定模块生成TOC：

.. autosummary::
　 mymodule
　 mymodule.submodule

这会生成名为generated/mymodule.rst和generated/mymodule.submodule.rst的文件，其中会包含前面提到的autodoc指令。使用同样的格式，还可以指定希望模块API的哪部分包含在文档中。

 提示

在大规模的项目中，手工添加模块到这个列表中是比较麻烦的。要记得conf.py是个普通的Python源文件，所以完全可以在里面写自己的代码，包括写代码去自动创建指明哪些模块需要生成文档的.rst文件。

Sphinx的另一个有用的功能是能够在生成文档时自动在例子上运行doctest。doctest是标准的Python模块，它能够针对代码片段搜索文档并运行代码以测试其是否反映代码的实际行为。每个以>>>（即主要的提示符）开始的段落会被看作是一个要测试的代码段。

To print something to the standard output, use the :py:func:`print` function.
　　>>> print("foobar")
　　foobar

在你的API演进的过程中很容易忘记对例子进行修改，doctest可以帮助你避免这类问题的发生。如果文档包含一份详细的分步指南，doctest能够确保其在开发过程中保持最新。也可以使用doctest做文档驱动开发（Documentation-Driven Development，DDD）：先写文档和例子，然后写代码去匹配文档。

通过特殊的doctest生成器，利用这个功能就像运行sphinx-build一样简单：

$ sphinx-build -b doctest doc/source doc/build
Running Sphinx v1.2b1
loading pickled environment... done
building [doctest]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
running tests...

Document: index
---------------
1 items passed all tests:
　 1 tests in default
1 tests in 1 items.
1 passed and 0 failed.
Test passed.

Doctest summary
===============
　　1 test
　　0 failures in tests
　　0 failures in setup code
　　0 failures in cleanup code
build succeeded.

Sphinx还提供了很多其他功能，自带或者通过扩展模块，包括

 
  • 项目间使用的链接；
  • HTML主题；
  • 图表和公式；
  • 输出为Texinfo和EPUB格式；
  • 链接到外部文档。

可能你现在并不需要所有这些功能，但是如果未来需要的话，提前知道有模块能提供这些功能还是不错的。