使用sphinx快速生成Python API 文档
来源:互联网 发布:推理小说推荐 知乎 编辑:程序博客网 时间:2024/04/30 07:04
不管是开源还是闭源,文档都是很重要的。当然理论上说,最好的文档就是代码本身,但是要让所有人都能读懂你的代码这太难了。所以我们要写文档。大部分情况,我们不希望维护一份代码再加上一份文档,这样做很容易造成文档和代码的不一致,程序员最讨厌更新文档了。所以最佳实践就是在程序员代码中加注释,然后通过构建脚本自通生成文档。
对应于Pyhon,有很多可供选择的工具:
sphinx 中文版介绍 Sphinx使用 reStructuredText作为标记语言(类似Markdown),可扩展,功能强大。要注意的是何有一个开源的搜索也叫Sphinx,斯芬克斯果然太受欢迎,开源的世界起个名字不容易呀。
pdoc 是一个简单易用的命令行工具,可以生成Python的API文档
Doxygen 是老牌的文档生成工具,可以针对各种语言生成文档,我们以前在C++的项目中曾经使用过
其他还有诸如 pydoc ,pydoctor 等等
下面我就介绍一下如果使用Sphinx为你的python项目快速的构建API 文档。
首先要安装Sphinx,不同的操作系统有不同的安装方式,Sphinx的源代码在这里 , 你也可以自己构建。我推荐使用pip install。(注,如果你安装了Anaconda,Sphinx已经包含在内了)
然后,假定你的python的源代码是在 src 目录下,我们在同一级并行建立一个文档目录 doc (你当然可以根据自己的项目需要,确定目录命名和结构)。
在doc目录下运行
sphinx会提示你的项目的一些设置,生成项目的配置文件,这里给出一些推荐的配置:
运行完毕,sphinx会生成项目的配置文档conf.py还有源文件(后缀为rst)
下一步要为捏python源文件生成sphinx的源文件,用来生成API文档,需要运行
其中outputdir是doc目录,packagedir是src目录,也就是你的python代码包所在的目录
运行好后,会对每一个Python包生成一个rst文件,你可以编辑该文件来修改生成文档的细节,一般情况下不用改。
好了,准备工作做好了以后,就可以生成API文档了。在运行文档生成脚本之前,要确保你的Python源代码所在的包在系统路径中是可以找到的,需要修改conf.py。因为在生成文档是需要运行你的python代码,要保证code运行不出错。
在doc目录下运行脚本
在output目录会生成HTML格式的API文档。(也可以选其他文档格式)
Sphinx还有一个automsummay的扩展,可能能简化以上的过程,等我试一试在更新结果。
- 使用sphinx快速生成Python API 文档
- 使用Sphinx为你的python模块自动生成文档
- 使用Sphinx为你的python模块自动生成文档
- Sphinx 生成HTML格式API文档
- Sphinx将python代码注释生成文档
- sphinx根据python注释生成文档
- 使用sphinx生成美观的文档
- javadoc--快速生成API文档
- snowboard快速生成api文档
- python自动生成易于阅读的html文档——使用Sphinx
- python自动生成易于阅读的html文档——使用Sphinx
- Sphinx API文档例子
- sphinx 使用 python xmlpipe2 数据源 生成索引
- 利用Sphinx轻松生成python代码的文档
- 利用Sphinx轻松生成python代码的文档
- python 文档生成器 sphinx
- 使用sphinx写文档
- sphinx使用整理文档
- 第 13 章 红黑树
- Spring MVC RedirectAttributes的用法
- linux NVMe驱动总结
- 树结构的定义,几种遍历方法
- 我理解的xpath实战应用
- 使用sphinx快速生成Python API 文档
- 我的 第一个微信小程序
- C++ DLL导出函数的两种方法(导出序号那种方法,别人看不到函数名)
- 使用循环CAS实现原子操作
- 优雅解决The android gradle plugin version 3.0.0-alpha1 is too old, update to the latest version
- 机器视觉学习笔记(4)——单目摄像机标定参数说明
- 用HTML5构建一个流程图绘制工具
- Linux常用命令
- 【Java高级开发工程师】近一个月的面试总结