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，則表示文檔生成成功。