利用Sphinx自动生成Python项目文档之二坑

sphinx doc 2016年08月27日 星期六

在上一篇中介绍了如何用Sphinx自动生成Python项目文档,在其过程中也发现了不少问题和关于样式上面有趣的事情。

坑一 :装饰器修饰的函数不会自动显示文档,比如flask,django 函数视图经常会用到装饰器,验证登录、返回JSON、捕捉异常等,可通过在装饰器中加入,wraps装饰器。

from functools import wraps

def wrapper():
    def _wrapper(_func):
        @wraps(_func)
        def __wrapper(*args, **kwargs):
            return _func()
        return __wrapper
    return _wrapper

坑二:celery的tasks都是自带的装饰器,不能如`坑一`一样去修改,需要在配置中增加支持。在conf.py中增加 celery.contrib.sphinx

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.ifconfig',
    # 'sphinx.ext.viewcode',
    'celery.contrib.sphinx',
]

坑三:若doc下各个模块的rst已生成,再去该模块添加新的文件则不会自动生成文档,最简单的办法就是删除对应模块的rst文件,执行以下命令去重新生成

sphinx-apidoc -o ./doc/ .

目前就这几点吧 . 后续有遇到在更新 ....