使用Sphinx为你的python模块自动生成文档
Sphinx是一个可以用于Python的自动文档生成工具,可以自动的把docstring转换为文档,并支持多种输出格式包括html,latex,pdf等。
安装
创建一个sphinx项目
下面的命令会自动生成一个默认的Sphinx模板
执行期间,它会一步步的询问对模板的设置,除了一些必须填写的选项,大部分填写默认值就行了,你会遇到这样一条叫autodoc的,需要选择yes
然后默认的目录就生成了,大概是这个样子
现在执行如下指令,就会生成一份空文档,存放在/build/html里,点击index.html就可以打开一个空的网页,虽然没有内容,但是整体的结构还是在的
source/ 目录
source/目录里有两个文件,分别是conf.py
和index.rst
,下面对它们进行进一步的介绍
index.rst
.rst是reStructuredText,和Markdown一样是一种标记语言,具体的语法可以看这里 reStructuredText Primer。
实际上,我们在使用Sphinx的过程中最主要就是对这些rst文件进行修改,而Sphinx所做的事情就是读取这些rst文件,并转换为特定格式的文档,在前面的步骤中,index.rst实际上被转换为build/html/index.html,而实际上在rst文档内你可以写任何东西,最后这些都会被转换到输出文档中。
打开index.rst,可以看到这样的内容,这是rst的一个语法,它使用了一个toctree节点,并设置了一些参数,而这个toctree节点是必须的。
conf.py
这是运行sphinx生成文档时会加载的配置,你可以通过对它进行修改来改变生成文档的行为。
一个具体的例子
假设现在我们有一个叫run.py的文件,如下
那么需要如何生成文档呢?下面一步步带你完成
- 创建一个文件夹demo/,并将run.py放到里面
- 在demo里创建一个docs目录,进入docs/目录,当然这里你可以随意选定文件夹,只是这样更规范一些
- 生成Sphinx默认模板,设置项目名为demo,并开启autodoc
运行sphinx-quickstart
- 进入source目录,打开index.rst
- 将index.rst 修改为如下,实际上这里面可以写任何满足rst规范的内容
这个是用于自动从模块读取docstring的语句,可以自动从run模块读取文档
- 但是现在还差一步,如果你现在直接生成文档,会告诉你找不到run模块,因为Sphinx默认只会从sys.path里加载模块,所以需要将demo目录加入sys.path,所以现在打开conf.py,添加如下内容
- 运行Sphinx生成html文档
现在,打开build/html/index.html就可以看到如下界面了
、
格式进一步优化
上面的例子涵盖了大多数常用操作,但是通常文档都不是扁平的,而是层次化的,那么要如何将文档层次化的分门别类。
实际上在rst文档中是可以以链接的形式引用其他rst文档的,也就是说我们可以自由的对文档结构进行组织使其更易读下面我们把run的文档移动到一个单独的页面,只在index.rst里保留跳转链接。在source目录下创建run.rst
然后将index.rst对应位置的内容删掉,并进行修改
:doc:'Run API</run>'
表示对一个文档的引用,这里引用了当前目录的run.rst,现在重新生成html,就会看到页面显示上的变化了。
使用Sphinx为你的python模块自动生成文档的更多相关文章
- 【Sphinx】 为Python自动生成文档
sphinx 前言 Sphinx是一个可以用于Python的自动文档生成工具,可以自动的把docstring转换为文档,并支持多种输出格式包括html,latex,pdf等 开始 建一个存放文档的do ...
- 使用doctest代码测试和Sphinx自动生成文档
python代码测试并自动生成文档 Tips:两大工具:doctest--单元测试.Sphinx--自动生成文档 1.doctest doctest是python自带的一个模块.doctest有两种使 ...
- eoLinker 新功能发布,增加了识别代码注释自动生成文档功能
产品地址:https://www.eolinker.com开源代码:https://www.eolinker.com/#/os/download在线生成代码注释工具:http://tool.eolin ...
- 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)
对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...
- MVC WEB api 自动生成文档
最近在一直在用webapi做接口给移动端用.但是让我纠结的时候每次新加接口或者改动接口的时候,就需要重新修改文档这让我很是苦恼.无意中发现.webapi居然有自动生成文档的功能....真是看见了救星啊 ...
- 使用swagger在netcorewebapi项目中自动生成文档
一.背景 随着前后端分离模式大行其道,我们需要将后端接口撰写成文档提供给前端,前端可以查看我们的接口,并测试,提高我们的开发效率,减少无效的沟通.在此情况下,通过代码自动生成文档,这种需求应运而生,s ...
- SpringBoot 集成Swagger2自动生成文档和导出成静态文件
目录 1. 简介 2. 集成Swagger2 2.1 导入Swagger库 2.2 配置Swagger基本信息 2.3 使用Swagger注解 2.4 文档效果图 3. 常用注解介绍 4. Swagg ...
- python代码docstring生成文档之sphinx
在使用python中,我们一般在模块,类,函数下使用docstring添加字符串说明性文档,使开发人员更好的可以看懂此代码是做什么用的.然而写了那么多的注释,我们想要一篇文档怎么办,第一种办法不可能将 ...
- 用doxygen自动生成文档
1. 添加符合doxygen解析规则的注释 (比如函数说明,函数参数/返回值说明) 用qt-creator可以在函数上方一行键入“/**”,然后直接回车,就可以自动生成默认的格式. 2. 安装doxy ...
随机推荐
- PAT Rational Sum
Rational Sum (20) 时间限制 1000 ms 内存限制 65536 KB 代码长度限制 100 KB 判断程序 Standard (来自 小小) 题目描述 Given N ration ...
- Fiddler 抓包工具总结【转载】
原博主连接在文章底部 Fiddler是一个蛮好用的抓包工具,可以将网络传输发送与接受的数据包进行截获.重发.编辑.转存等操作.也可以用来检测网络安全.反正好处多多,举之不尽呀!当年学习的时候也蛮费劲, ...
- [NOIP 2014TG D1T3] 飞扬的小鸟
题目描述 Flappy Bird 是一款风靡一时的休闲手机游戏.玩家需要不断控制点击手机屏幕的频率来调节小鸟的飞行高度,让小鸟顺利通过画面右方的管道缝隙.如果小鸟一不小心撞到了水管或者掉在地上的话,便 ...
- 使用JQuery 合并两个 json 对象
一,保存object1和2合并后产生新对象,若2中有与1相同的key,默认2将会覆盖1的值 var object = $.extend({}, object1, object2); 二,将2的值合并到 ...
- rsyslog的配置文件使用方法
参考地址: http://www.rsyslog.com/doc/v8-stable/configuration/property_replacer.html rsyslog消息模板的定义规则 &qu ...
- Eclipse错误:The superclass "javax.servlet.http.HttpServlet" was not found on the Java Build Path
该报错是由于缺少servlet-api.jar造成的,将servlet-api.jar复制到项目下的WEB-INF/lib目录下即可 servlet-api.jar在tomcat的lib目录下有,可以 ...
- 在引用的laravel的@include子模板中传递参数
调用传参: @include("message",['msg'=>'中国']) 在message子模板中调用msg的值: {{msg}}
- OOP⑶
/** * 学生类 * ctrl+o 查询本类的所有属性 和方法 */ public class Student { int age; // 年龄 String name; // 姓名 // 自己创建 ...
- CSS(三)--自定义标签
HTML代码 <body> <ul> <li>1</li> <li>2</li> </ul> </body&g ...
- Java 如何抛出异常、自定义异常
Java错误与异常的基本概念: 1.java中异常均继承自Throwable,其有两个重要的直接子类error与exception. 2.java错误error,大部分是由虚拟机爆出来的错误,是程序无 ...