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