写好了代码,交付给他人使用的时候,查看代码固然可以了解各类和函数的功能细节,但接口文档能更方便的查找和说明功能。所以,一价与代码同步的接口文档是很有必要的。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中的注释成为接口文档的更多相关文章

  1. 快速根据注释生成接口文档网页工具——Apidoc的使用教程

    1,安装Node.js的npm工具环境: 如有不懂,请看我的博客:“https://blog.csdn.net/sinat_28371057/article/details/81612661“ 2,n ...

  2. 在.Net Core中使用Swagger制作接口文档

    在实际开发过程中后台开发人员与前端(移动端)接口的交流会很频繁.所以需要一个简单的接口文档让双方可以快速定位到问题所在. Swagger可以当接口调试工具也可以作为简单的接口文档使用. 在传统的asp ...

  3. 使用Sandcastle 基于代码注释生成接口文档

    一. 工具下载: 1. Sandcastle:Sandcastle是微软官方的文档生成工具,下载地址:http://www.codeplex.com/Sandcastle 2. SHFBGuidedI ...

  4. php类注释生成接口文档

    参考地址:https://github.com/itxq/api-doc-php

  5. 使用sphinx快速为你python注释生成API文档

    sphinx简介sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的, ...

  6. Python中的注释(转)

    一.单行注释     单行注释以#开头,例如:     print 6 #输出6 二.多行注释     (Python的注释只有针对于单行的注释(用#),这是一种变通的方法)      多行注释用三引 ...

  7. 怎样在python中写注释

    python中的注释是以井号: # 开头, 一般会在#后加一个空格. # This is a comment print("Hello, World!") 多行注释的语法是三引号: ...

  8. 在sublime3中docblockr插件配置apidoc接口文档注释模板

    写在前面: 将进行3个步骤配置 1.在sublime3中安装插件docblockr,可以参考http://www.cnblogs.com/jiangxiaobo/p/8327709.html 2.安装 ...

  9. 使用sphinx制作接口文档并托管到readthedocs

    此sphinx可不是彼sphinx,此篇是指生成文档的工具,是python下最流行的文档生成工具,python官方文档即是它生成,官方网站是http://www.sphinx-doc.org,这里是一 ...

随机推荐

  1. 分布式系统:CAP

    一致不太理解CAP,最近好像有点感觉了,这里写下来,先介绍下CAP的定义: C:一致性.写完数据后,立马能看到最新数据. A:可用性.所有请求必须有响应. P:分区容错性.网络或服务器故障不会导致系统 ...

  2. Asp.Net Mvc3.0(MEF依赖注入理论)

    前言 Managed Extensibility Framework(MEF)是.NET平台下的一个扩展性管理框架,它是一系列特性的集合,包括依赖注入(DI)等.MEF为开发人员提供了一个工具,让我们 ...

  3. 《SEO教程:搜索引擎优化入门与进阶(第3版)》

    <SEO教程:搜索引擎优化入门与进阶(第3版)> 基本信息 作者: 吴泽欣 丛书名: 图灵原创 出版社:人民邮电出版社 ISBN:9787115357014 上架时间:2014-7-1 出 ...

  4. docker 删除无用的镜像文件的命令小计

    df -h  查看当前服务器的内存情况 docker system prune  删除无用镜像文件命令 执行ok之后,再次查看内存情况.

  5. <A>标签电子邮件链接

    电子邮件链接 – 要链接电子邮件,可在链接标签中插入” mailto:邮箱地址” <A href="mailto:webmaster@sohu.com"> 站长信箱 & ...

  6. 如何选择JAVA培训机构,兼议什么样的人适合培训机构

    首先,利益相关,本人就是培训机构创办者兼讲师,但这不妨碍我对此发表看法. 我们先来看什么样的人适合培训机构?要回答这个问题,需要先换个角度.这个角度就是,你学习一门语言的动机是什么?99%的人的回答是 ...

  7. spring boot成功启动后访问报错404的问题

    Whitelabel Error Page This application has no explicit mapping for /error, so you are seeing this as ...

  8. iOS:仿写探探App动画

    一.简单介绍 探探动画比较新颖,这也是它在众多交友软件中火热的一个特色.实现这种动画的方式可以有两种方式实现: 1.使用转场动画实现  2.使用CollectionView自定义布局实现, 此处我提供 ...

  9. 命令行调用dubbo远程服务

    命令行调用dubbo远程服务 telnet远程连接到dubbo telnet 127.0.0.1 20880 查看提供服务的接口 dubbo>ls com.test.service.TestIn ...

  10. Go语言之进阶篇TCP相互通信

    1.TCP相互通信 服务端示例: tcp_server.go package main import ( "fmt" "net" ) func main() { ...