sphinx-python文档化

概述

下文讲述使用sphinx自动生成reStructuredText python API文档的简单过程。

配置流程

安装依赖

$ pip install sphinx blurb python-docs-theme

创建项目

$ mkdir demo
$ cd demo

# 自动生成配置文件
demo $ sphinx-quickstart

项目相关文件说明（以默认配置为例）

项目结构：

# demo/

conf.py
Makefile
make.bat
_build/
|--doctrees/
  |--environment.pickle
  |--index.doctree
|--html/
  |--_sources/
  |--_static/
  index.html
  ...
_static/
_templates/
index.rst

其中index.rst是入口文件，sphinx生成文档的实质是根据配置遍历路径内文件并提取docstring进行渲染的过程，过程大致可划分为两步：第一步是根据conf.py配置启动文件，第二步是根据index.rst的指令渲染html文件。

假设项目的python源代码放置在app/目录下：

demo $ mkdir app
demo $ mkdir app/__init__.py

实现文件功能：

# demo/app/__init__.py

def run(host, port):
    """
    run server on given host:port

    :type host: str
    :param host: server host
    :type port: int
    :param port: server port

    :return app

    """
    print('running on :{}:{}'.format(host, port))
    return 0
    

配置文件

此时还sphinx还不知道原代码文档写在哪里，需要在index.rst文件中配置：

Welcome to sphinx-demo's documentation!
=======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


API
====

.. automodule:: app
   :members:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

配置的信息是API部分内容，这相当于告诉sphinx要生成该模块docstring的对应文档。

除了配置index.rst文档，还需要在conf.py中修改两个地方：添加导入路径和添加插件，这是由于sphinx默认只会从sys.path路径中执行导入操作，要让sphinx知道上述模块的路径，需要执行如下更改：

# conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

...

extensions = [
    'sphinx.ext.autodoc'
]

做到这一步，就可以执行文档生成操作：

demo $ make html .
# 或
demo $ sphinx-build . _build/

命令执行完毕就会在 _build/html下生成html文件，其中入口就是index.html。

总结

这就是python自动生成文档的步骤，更加深入的知识可以参考一下内容：

reStructureText文档
conf.py配置文件说明
sphinx-build命令
python文档化