Python寫自動化之使用sphinx提取Python代碼docstring

標籤：sphinx   doc   文檔   python   

在使用Python時，一個特性是Python中的文檔字串，文檔字串又稱為DocStrings。使用文檔字串可以為我們的模組、類、函數添加說明性文檔，使程式更容易被看懂。這好像和其他語言中的注釋沒什麼區別，然而，Python中的文檔字串特殊在於Python提供了相應的方法，可以將這些說明性的文檔輸出。

假設有如下的函數：

def Test():    ‘‘‘    | ##@function: test    | ##@description：test    | ##@return value：None    | ##@logic：test    | ##@warning：test    ‘‘‘    import atf.plugin.DesktopCommon as DesktopCommon    DesktopCommon.StopProcess("notepad")

我們使用 Test.__doc__ 就可以得到Test()函數的說明文檔，並且，調用help函數，實際上得到的內容也是該函數的說明文檔。也就是說，help(Test)，實際上輸出的內容就是Test()函數的說明文檔。

Sphinx是一個第三方工具，可以提取Python代碼中的說明文檔，並產生html檔案。介紹一下如何用Sphinx產生Python代碼的API文檔。

首先需要安裝Sphinx，安裝的方法有多種，可以直接用easy_install 安裝，也可以用其他的方法安裝。安裝之後，需要在將python的scripts目錄添加到系統內容變數中，如 C:\\python27\\Scripts。

現在就可以產生Python檔案的文檔了。

假設我們的代碼檔案在D:\\test 目錄下面。

（1）在命令列視窗中進入D:\\test 目錄下，運行 sphinx-quickstart

之後sphinx會提示讓對項目進行一些設定，以產生項目的設定檔，下面是一個推薦的配置：

> Root path for the documentation [.]:<ENTER>> Separate source and build directories (y/N) [n]:y> Name prefix for templates and static dir [_]:<ENTER>> Project name:an_example_pypi_project> Author name(s):Andrew Carter> Project version:0.0.1> Project release [0.0.1]:<ENTER>> Source file suffix [.rst]:<ENTER>> Name of your master document (without suffix) [index]:<ENTER>> autodoc: automatically insert docstrings from modules (y/N) [n]:y> doctest: automatically test code snippets in doctest blocks (y/N) [n]:n> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:y> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]:n> coverage: checks for documentation coverage (y/N) [n]:n> pngmath: include math, rendered as PNG images (y/N) [n]:n> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:n> ifconfig: conditional inclusion of content based on config values (y/N) [n]:y> Create Makefile? (Y/n) [y]:n> Create Windows command file? (Y/n) [y]:n

運行完之後，會在目前的目錄下產生source檔案夾，並且source檔案夾下會有conf.py 和 index.rst檔案

（2）修改conf.py檔案。目的是確保python原始碼所在的包在系統路徑中可以找到。

將 sys.path.insert(0,os.path.abspath(‘.‘)) 改為 sys.path.insert(0,os.path.abspath(‘..‘)) ，並去掉注釋

（3）產生rst檔案

命令列下運行： sphinx-apidoc -o outputdir packagedir

其中：outputdir是source的目錄，packagedir是代碼所在的目錄

（4）產生rst檔案後，就可以產生html檔案了。進入到source目錄下，運行：

sphinx-build -b html . ./output

會在source目錄下產生output檔案夾，並且產生的html檔案都在output檔案夾內。

Python寫自動化之使用sphinx提取Python代碼docstring