Python中的多行注释文档编写风格汇总


Posted in Python onJune 16, 2016

什么是docstring

在软件工程中,其实编码所占的部分是非常小的,大多是其它的事情,比如写文档。文档是沟通的工具。
在Python中,比较推崇在代码中写文档,代码即文档,比较方便,容易维护,直观,一致。
代码写完,文档也出来了。其实Markdown也差不多这种思想,文本写完,排版也完成了。
看看PEP 0257中对docstring的定义:

A docstring is a string literal that occurs as the first statement in
a module, function, class, or method definition. Such a docstring
becomes the __doc__ special attribute of that object.
简单来说,就是出现在模块、函数、类、方法里第一个语句的,就是docstring。会自动变成属性__doc__。

def foo():
  """ This is function foo"""

可通过foo.__doc__访问得到' This is function foo'.

各类docstring风格:

Epytext

这是曾经比较流行的一直类似于javadoc的风格。

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

reST

这是现在流行的一种风格,reST风格,Sphinx的御用格式。我个人也是喜欢用这种风格,比较紧凑。

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

Google风格

"""
This is a groups style docs.

Parameters:
  param1 - this is the first param
  param2 - this is a second param

Returns:
  This is a description of what is returned

Raises:
  KeyError - raises an exception
"""

Numpydoc (Numpy风格)

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
  the 1st param name `first`
second :
  the 2nd param
third : {'value', 'other'}, optional
  the 3rd param, by default 'value'

Returns
-------
string
  a value in a string

Raises
------
KeyError
  when a key error
OtherError
  when an other error
"""

docstring工具之第三方库pyment

用来创建和转换docstring.
使用方法就是用pyment生成一个patch,然后打patch。

$ pyment test.py      #生成patch
$ patch -p1 < test.py.patch #打patch

详情:https://github.com/dadadel/pyment

使用sphinx的autodoc自动从docstring生产api文档,不用再手写一遍

我在代码中已经写过docstring了,写api文档的内容跟这个差不多,难道要一个一个拷贝过去rst吗?当然不用。sphinx有autodoc功能。
首先编辑conf.py文件,
1. 要有'sphinx.ext.autodoc'这个extensions
2. 确保需要自动生成文档的模块可被import,即在路径中。比如可能需要sys.path.insert(0, os.path.abspath(‘../..'))

然后,编写rst文件,

xxx_api module
---------------------

.. automodule:: xxx_api
  :members:
  :undoc-members:
  :show-inheritance:
敲make html命令,就可以从docstring中生成相关的文档了,不用多手写一遍rst.
看效果:
Python中的多行注释文档编写风格汇总
Python 相关文章推荐
使用Python的web.py框架实现类似Django的ORM查询的教程
May 02 Python
rabbitmq(中间消息代理)在python中的使用详解
Dec 14 Python
Python数据拟合与广义线性回归算法学习
Dec 22 Python
python SSH模块登录,远程机执行shell命令实例解析
Jan 12 Python
Python面向对象之接口、抽象类与多态详解
Aug 27 Python
python之消除前缀重命名的方法
Oct 21 Python
Python增强赋值和共享引用注意事项小结
May 28 Python
python 实现返回一个列表中出现次数最多的元素方法
Jun 11 Python
使用selenium和pyquery爬取京东商品列表过程解析
Aug 15 Python
解决Jupyter Notebook开始菜单栏Anaconda下消失的问题
Apr 13 Python
python 绘制国旗的示例
Sep 27 Python
Python构造自定义方法来美化字典结构输出的示例
Jun 16 #Python
浅谈Python中chr、unichr、ord字符函数之间的对比
Jun 16 #Python
详解Python中 __get__和__getattr__和__getattribute__的区别
Jun 16 #Python
Python利用带权重随机数解决抽奖和游戏爆装备问题
Jun 16 #Python
Python黑魔法@property装饰器的使用技巧解析
Jun 16 #Python
Python实现类似jQuery使用中的链式调用的示例
Jun 16 #Python
浅析Python中else语句块的使用技巧
Jun 16 #Python
You might like
图书管理程序(三)
2006/10/09 PHP
解析PHP跨站刷票的实现代码
2013/06/18 PHP
PHP+iframe模拟Ajax上传文件功能示例
2019/07/02 PHP
JQuery实现自定义对话框的代码
2008/06/15 Javascript
了解一点js的Eval函数
2012/07/26 Javascript
分享8款优秀的 jQuery 加载动画和进度条插件
2012/10/24 Javascript
jquery实现微博文字输入框 输入时显示输入字数 效果实现
2013/07/12 Javascript
jquery遍历数组与筛选数组的方法
2013/11/05 Javascript
仿百度联盟对联广告实现代码
2014/08/30 Javascript
jQuery采用连缀写法实现的折叠菜单效果
2015/09/18 Javascript
简要了解jQuery移动web开发的响应式布局设计
2015/12/04 Javascript
zTree插件下拉树使用入门教程
2016/04/11 Javascript
两种JavaScript的AES加密方式(可与Java相互加解密)
2016/08/02 Javascript
图文详解JavaScript的原型对象及原型链
2016/08/02 Javascript
JS获取当前地理位置的方法
2017/10/25 Javascript
vue中使用element-ui进行表单验证的实例代码
2018/06/22 Javascript
Ant design vue table 单击行选中 勾选checkbox教程
2020/10/24 Javascript
[03:44]2014DOTA2国际邀请赛 71专访:DK战队赛前讨论视频遭泄露
2014/07/13 DOTA
[02:33]2018 DOTA2亚洲邀请赛回顾视频 再次拾起那些美妙的时刻
2018/04/10 DOTA
整理Python中的赋值运算符
2015/05/13 Python
python中文件变化监控示例(watchdog)
2017/10/16 Python
详解python中asyncio模块
2018/03/03 Python
《与孩子一起学编程》python自测题
2018/05/27 Python
NumPy 数学函数及代数运算的实现代码
2018/07/18 Python
Python 互换字典的键值对实例
2019/02/12 Python
Python中将两个或多个list合成一个list的方法小结
2019/05/12 Python
python按行读取文件并找出其中指定字符串
2019/08/08 Python
纯HTML5+CSS3制作图片旋转
2016/01/12 HTML / CSS
HTML5实现简单图片上传所遇到的问题及解决办法
2016/01/20 HTML / CSS
俄罗斯优惠券网站:BIGLION
2017/05/21 全球购物
北美三大旅游网站之一:Travelocity
2017/08/12 全球购物
Perfume’s Club中文官网:西班牙美妆在线零售品牌
2020/08/24 全球购物
入党转预备思想汇报
2014/01/07 职场文书
人力资源经理的岗位职责范本
2014/02/28 职场文书
2014年班长个人工作总结
2014/11/14 职场文书
MySQL系列之三 基础篇
2021/07/02 MySQL