Python写自动化之使用sphinx提取Python代码docstring

在使用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: