python文档的自动生成

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

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

   pip install sphinx
              

3. 创建文档生成的文件夹

   创建一个名为doc的文件夹，用来存放生成文档的脚本及文档存储。

4. 生成文档配置及执行脚本

   在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的文件，说明上面命令执行完成

5. 修改配置文件

   为了让能够支持文档自动生成还需要对 doc/source/conf.py进行修改

   • 支持文档自动生成

     修改conf.py的33行的extensions， 自动生成的是extensions = []，需要将其更改为extensions = [‘sphinx.ext.autodoc’]，否则后续执行会报错。

   • 配置源代码路径

     将conf.py中的13-15行注释去除，并将15行修改为以下代码：

6. 生成rst文件

   命令行切换到doc目录下，执行如下命令：

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

   执行完后会在doc/source下会生成一系列的rst文件，文档就是基于这些rst文件生成html

7. 生成文档的html

   命令行保持在doc目录下，执行如下命令：

   make html
              

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