使用doxygen自动对python api做接口文档及生成帮助文档

womende3ban

已于 2023-05-30 09:38:39 修改

阅读量1.2k

点赞数

文章标签： python 文档资料

于 2023-05-25 16:22:58 首次发布

本文链接：https://blog.youkuaiyun.com/womende3ban/article/details/130866951

版权

项目背景：有个大型的python做后台的项目需要编写一个api接口文档接口类里面前前后后封装了块200+快300个函数接口，有一个是word版本的之前一直维护的文档。

需要的是制作好后的文档，最好有接口函数名称（中/英）文的引索，正文可以搜索（模糊检索），方便查询操作接口函数用以编制自动测试用的脚本。大概就是MSDN那种可以搜索的大型接口文本

路径1:使用Word2CHM 或 doc2CHM软件，将word类文档直接转成CHM，缺点就是标题转为引索。原本的word文档中的函数是以表格形式存在，可以正常转为HTML显示，但引索是word的标题而且还会因为 chm在windows下的软件仅支持GB2312而实际word转html为unicode造成乱码。这个乱码同时会影响到搜索

路径2:使用doxygen重新搜索代码的对外接口类，让其从函数的注释中自动生成文档。
这里推荐《doxygen中文手册v1.63》，里面有详细的使用说明。
本文简略提及一下：
doxygen支持python的函数文档有两种格式。一种是类似于javadoc的格式可以搜索到函数的名称和参数信息类似于这样如下这样的

	## 打印并记录log信息
	# @param log string格式 需要输出的字符串
	# @param saveStep 是否记录到数据库中
	# @exception N/A
	# @return return log字符串本身
	def printLog(self, log, saveStep = False):	
		Client.output_log(self.task_id, log)
		if saveStep :
			DataBaseRecord.writeLogInfo(log)
		return log

doxygen可以正确的解析@param表示符号后的信息，并把第一个##后的作为函数名称

还有一种常见的py注释格式如下

	def printLog(self, log, saveStep = False):	
		''' 打印并记录log信息
		:param log: string格式 需要输出的字符串}
		:param saveStep: 是否记录到数据库中
		:exception: N/A
		:returns: 字符串本身 或 False - 打印失败
		'''
		Client.output_log(self.task_id, log)
		if saveStep :
			DataBaseRecord.writeLogInfo(log)
		return log