使用sphinx自动提取python中的注释成为接口文档
写好了代码,交付给他人使用的时候,查看代码固然可以了解各类和函数的功能细节,但接口文档能更方便的查找和说明功能。所以,一价与代码同步的接口文档是很有必要的。sphinx可以根据python中的注释,自动的生成接口文档,这样有利于保证文档和代码功能的同步。让我们来了解如何自动生成文档。
1. python代码格式。
class A:
'''
你好!
'''
@staticmethod
def Aa():
'''
你也好!
'''
fun1()
看到类和函数中,都加入了注释。
2. 安装shpinx
pip install sphinx -i https://pypi.doubanio.com/simple --trusted-host pypi.doubanio.com
使用国内的镜像安装比较快。
3. 配置shpinx
$ cd myproject
$ sphinx-quickstart
Enter the root path for documentation.
> Root path for the documentation [.]: doc
> Project name: XXX
> Author name(s): XXX
> Project version []: 1.0
> Project release [1.0]:
> Project language [en]: zh_CN #如果注释中有中文,这里必须设置。否则生成接口文档出错。
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
其它项都选择默认
完成之后,会在当前目录创建 doc 目录,所有sphinx相关的文件都在 doc目录下。
$ ls doc/
_build conf.py index.rst Makefile _static _templates
$ vi doc/conf.py #修改文件内容
sys.path.insert(, os.path.abspath('.'))
sys.path.insert(, os.path.abspath('..')) # 缺少此行会导致在make html时提示 __import__出错,找不到module。 所以必须把上一级目录(即代码所在目录)include进来 $ sphinx-apidoc -o doc/ .
Creating file doc/a.rst.
Creating file doc/modules.rst # 把生成的 doc/modules.rst添加到index.rst
$ vi doc/index.rst Contents:
.. toctree::
:maxdepth: modules.rst 生成html页面
$ cd doc
$ make html
生成的html文档,在doc/_build/html里。
sphinx对仅工作在python2.7 或python3上。当文件中有中文时,可能会报错:'ascii' codec can't decode byte 0xe2 in position xxx。可以在报错的地方加入:
import sys
reload(sys)
sys.setdefaultencoding('utf-8')
使用sphinx自动提取python中的注释成为接口文档的更多相关文章
- 快速根据注释生成接口文档网页工具——Apidoc的使用教程
1,安装Node.js的npm工具环境: 如有不懂,请看我的博客:“https://blog.csdn.net/sinat_28371057/article/details/81612661“ 2,n ...
- 在.Net Core中使用Swagger制作接口文档
在实际开发过程中后台开发人员与前端(移动端)接口的交流会很频繁.所以需要一个简单的接口文档让双方可以快速定位到问题所在. Swagger可以当接口调试工具也可以作为简单的接口文档使用. 在传统的asp ...
- 使用Sandcastle 基于代码注释生成接口文档
一. 工具下载: 1. Sandcastle:Sandcastle是微软官方的文档生成工具,下载地址:http://www.codeplex.com/Sandcastle 2. SHFBGuidedI ...
- php类注释生成接口文档
参考地址:https://github.com/itxq/api-doc-php
- 使用sphinx快速为你python注释生成API文档
sphinx简介sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的, ...
- Python中的注释(转)
一.单行注释 单行注释以#开头,例如: print 6 #输出6 二.多行注释 (Python的注释只有针对于单行的注释(用#),这是一种变通的方法) 多行注释用三引 ...
- 怎样在python中写注释
python中的注释是以井号: # 开头, 一般会在#后加一个空格. # This is a comment print("Hello, World!") 多行注释的语法是三引号: ...
- 在sublime3中docblockr插件配置apidoc接口文档注释模板
写在前面: 将进行3个步骤配置 1.在sublime3中安装插件docblockr,可以参考http://www.cnblogs.com/jiangxiaobo/p/8327709.html 2.安装 ...
- 使用sphinx制作接口文档并托管到readthedocs
此sphinx可不是彼sphinx,此篇是指生成文档的工具,是python下最流行的文档生成工具,python官方文档即是它生成,官方网站是http://www.sphinx-doc.org,这里是一 ...
随机推荐
- 分布式系统:CAP
一致不太理解CAP,最近好像有点感觉了,这里写下来,先介绍下CAP的定义: C:一致性.写完数据后,立马能看到最新数据. A:可用性.所有请求必须有响应. P:分区容错性.网络或服务器故障不会导致系统 ...
- Asp.Net Mvc3.0(MEF依赖注入理论)
前言 Managed Extensibility Framework(MEF)是.NET平台下的一个扩展性管理框架,它是一系列特性的集合,包括依赖注入(DI)等.MEF为开发人员提供了一个工具,让我们 ...
- 《SEO教程:搜索引擎优化入门与进阶(第3版)》
<SEO教程:搜索引擎优化入门与进阶(第3版)> 基本信息 作者: 吴泽欣 丛书名: 图灵原创 出版社:人民邮电出版社 ISBN:9787115357014 上架时间:2014-7-1 出 ...
- docker 删除无用的镜像文件的命令小计
df -h 查看当前服务器的内存情况 docker system prune 删除无用镜像文件命令 执行ok之后,再次查看内存情况.
- <A>标签电子邮件链接
电子邮件链接 – 要链接电子邮件,可在链接标签中插入” mailto:邮箱地址” <A href="mailto:webmaster@sohu.com"> 站长信箱 & ...
- 如何选择JAVA培训机构,兼议什么样的人适合培训机构
首先,利益相关,本人就是培训机构创办者兼讲师,但这不妨碍我对此发表看法. 我们先来看什么样的人适合培训机构?要回答这个问题,需要先换个角度.这个角度就是,你学习一门语言的动机是什么?99%的人的回答是 ...
- spring boot成功启动后访问报错404的问题
Whitelabel Error Page This application has no explicit mapping for /error, so you are seeing this as ...
- iOS:仿写探探App动画
一.简单介绍 探探动画比较新颖,这也是它在众多交友软件中火热的一个特色.实现这种动画的方式可以有两种方式实现: 1.使用转场动画实现 2.使用CollectionView自定义布局实现, 此处我提供 ...
- 命令行调用dubbo远程服务
命令行调用dubbo远程服务 telnet远程连接到dubbo telnet 127.0.0.1 20880 查看提供服务的接口 dubbo>ls com.test.service.TestIn ...
- Go语言之进阶篇TCP相互通信
1.TCP相互通信 服务端示例: tcp_server.go package main import ( "fmt" "net" ) func main() { ...