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

时间：2015-03-31 14:52:51 阅读：344 评论：0 收藏：0 [点我收藏+]

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