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

Posted 2020-07-06

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: 用于填写查询条件

#注意空一行

‘‘‘