利用sphinx为python项目生成API文档

时间:2021-03-13 16:44:55

sphinx可以根据python的注释生成可以查找的api文档,简单记录了下步骤

1:安装 pip install -U Sphinx

2:在需要生成文档的.py文件目录下执行sphinx-apidoc -F -o ./doc ./domain/model/ 在当前目录下新建doc目录,api文档的文件夹就在此目录下,./domain/model/ 表示需要生成api文档的目录。
3:进入doc目录 修改conf.py文件 设置代码路径为sys.path.insert(0, os.path.abspath('../domain'))。保存。
4:在doc目录下执行make html 生成html文件 
5:在smb服务器上,打开/doc/_build/html 的index.html文件 查看文档
 
函数文档的格式:
例子:/trunk/server/domain/model/customer/customer.py 文件def find_by_like(cls, input, limit=10)函数
需要写明函数是干啥的。 函数的形参和返回值的意义。
 
函数行参和函数返回值编写格式如下:(只有按照如下格式编写,文档生成才会正确)
'''
函数功能说明
#注意空一行
:return: 返回一个通过模糊查找的 :attr:`Customer` 对象列表
         查询到的数量由 `limit` =10控制
:param input: 用于填写查询条件
#注意空一行
'''