python文档的自动生成

在python代码中我们使用文档注释，然后再通过使用sphinx就可以生成相关的文档了。下面详细介绍下相关步骤：

0. 假设我们已经存在了一个项目名为doc_test，项目下存在一个src文件夹，里面存放我们的源代码。
1. 安装sphinx

   pip install sphinx
   

2. 创建文档生成的文件夹
   创建一个名为doc的文件夹，用来存放生成文档的脚本及文档存储。
3. 生成文档配置及执行脚本
   在doc文件夹下执行如下操作：

   sphinx-quickstart
   ... 接下来会出现下面的配置，可根据自己的项目情况填写
   > Separate source and build directories (y/n) [n]: y
   > Project name: test
   > Author name(s): fcat
   > Project release []: 1.0.0
   > Project language [en]: zh-CN
   

   执行完之后会在doc文件夹下生成make.bat的文件，说明上面命令执行完成
4. 修改配置文件
   为了让能够支持文档自动生成还需要对 doc/source/conf.py进行修改
   • 支持文档自动生成
     修改conf.py的33行的extensions， 自动生成的是extensions = []，需要将其更改为extensions = [‘sphinx.ext.autodoc’]，否则后续执行会报错。
   • 配置源代码路径
     将conf.py中的13-15行注释去除，并将15行修改为以下代码：

     sys.path.insert(0, os.path.abspath('./../../src'))
     

5. 生成rst文件
   命令行切换到doc目录下，执行如下命令：

   sphinx-apidoc -o ./source ../src/ 
   

   执行完后会在doc/source下会生成一系列的rst文件，文档就是基于这些rst文件生成html
6. 生成文档的html
   命令行保持在doc目录下，执行如下命令：

   make html
   

   执行完毕后会生成doc/build/html/index.html，则表示文档生成成功。