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