3.3　扩展Sphinx

有时现成的方案还不够。如果你写的是一个在Python内部调用的API那么问题不大，但如果写的是一个HTTP REST API，Sphinx就只能为你的API生成Python端的文档，因此你不得不手工编写REST API文档应处理随之而来的其他问题。

WSME（https://pypi.python.org/pypi/WSME）的创建者们有别的主意。他们开发了一个名为sphinxcontrib-pecanwsme（https://pypi.python.org/pypi/sphinxcontrib-pecanwsme）的Sphinx的扩展，它可以分析文档字符串和实际的Python代码并自动生成REST API文档。你也可以对自己的项目这么做，将代码中的有用信息抽取到文档中，只有让这个过程自动化才有意义。

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

 提示

针对其他HTTP框架，如Flask、Bottle和Tornado，可以使用sphinxcontrib.httpdomain（http://pythonhosted.org/sphinxcontrib-httpdomain/）。我个人的观点是，无论任何时候，只要能从代码中抽取信息帮助生成文档，都值得去做并且将其自动化。这比手工维护文档要好得多，尤其是可以利用自动发布工具（如Read The Docs）的时候。

要开发Sphinx，首先是要编写一个模块，最好是作为sphinxcontrib的一个子模块（如果模块足够通用的话），并且起个名字。Sphinx需要该模块有个预定义的名为setup(app)的函数。app对象会包含用来将你的代码连接到Sphinx事件和指令的方法。完整的方法列表可以在Sphinx扩展API（http://sphinx-doc.org/ext/appapi.html）中找到。

例如，sphinxcontrib-pecanwsme利用setup(app)函数添加了一个名为rest-controller的单条指令。添加的这条指令需要WSME控制器的类名是完整的限定名来为其生成文档。

示例3.1　摘自sphinxcontrib.pecanwsme.rest.setup的代码

def setup(app):
　　app.add_directive('rest-controller', RESTControllerDirective)

RESTControllerDirective是个指令类，它必须包含特定的属性和方法，就像在Sphinx扩展API（http://sphinx-doc.org/ext/appapi.html#sphinx.application.Sphinx.add_directive）中描述的那样。主方法run()会负责完成从代码中抽取文档的实际工作。

sphinx-contrib资源库（https://bitbucket.org/birkenfeld/sphinx-contrib/src）包括一组能够帮助你开发自己的扩展模块的小模块。

 注意

尽管Sphinx是用Python开发的，而且默认也主要面向Python，但是它有很多可用的扩展使它可以支持其他语言。所以，即使项目同时使用了多种语言，也可以用Sphinx为整个项目生成文档。