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实现在线程里运行scrapy的方法
Apr 07 Python
python通过imaplib模块读取gmail里邮件的方法
May 08 Python
详解Python实现多进程异步事件驱动引擎
Aug 25 Python
Python使用Matplotlib实现Logos设计代码
Dec 25 Python
对pandas处理json数据的方法详解
Feb 08 Python
pandas数据集的端到端处理
Feb 18 Python
python语言元素知识点详解
May 15 Python
python3.7通过thrift操作hbase的示例代码
Jan 14 Python
python实现加密的方式总结
Jan 19 Python
使用python创建Excel工作簿及工作表过程图解
May 27 Python
基于Python爬取fofa网页端数据过程解析
Jul 13 Python
用Python爬虫破解滑动验证码的案例解析
May 06 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
PHP setcookie设置Cookie用法(及设置无效的问题)
2011/07/13 PHP
实例详解PHP中html word 互转的方法
2016/01/28 PHP
PHP的swoole扩展安装方法详细教程
2016/05/18 PHP
微信公众号开发客服接口实例代码
2016/10/21 PHP
PHP一个简单的无需刷新爬虫
2019/01/05 PHP
JavaScript中SQL语句的应用实现
2010/05/04 Javascript
Ajax 数据请求的简单分析
2011/04/05 Javascript
仅IE9/10同时支持script元素的onload和onreadystatechange事件分析
2011/04/27 Javascript
jquery构造器的实现代码小结
2011/05/16 Javascript
JQuery入门——用one()方法绑定事件处理函数(仅触发一次)
2013/02/05 Javascript
javascript结合html5 canvas实现(可调画笔颜色/粗细/橡皮)的涂鸦板
2013/04/27 Javascript
Jquery方式获取iframe页面中的 Dom元素
2014/05/07 Javascript
项目中常用的JS方法整理
2015/01/30 Javascript
深入学习JavaScript对象
2015/10/13 Javascript
封装好的javascript前端分页插件pagination
2016/01/04 Javascript
bootstrap的常用组件和栅格式布局详解
2017/05/02 Javascript
vue+webpack实现异步组件加载的方法
2018/02/03 Javascript
微信小程序项目实践之主页tab选项实现
2018/07/18 Javascript
微信小程序实现页面下拉刷新和上拉加载功能详解
2018/12/03 Javascript
js实现无缝轮播图
2020/03/09 Javascript
JS变量提升及函数提升实例解析
2020/09/03 Javascript
[00:32]2018DOTA2亚洲邀请赛iG出场
2018/04/03 DOTA
python发送邮件功能实现代码
2016/07/15 Python
python+opencv识别图片中的圆形
2020/03/25 Python
Python xlrd excel文件操作代码实例
2020/03/10 Python
Pytorch 高效使用GPU的操作
2020/06/27 Python
python中tkinter窗口位置\坐标\大小等实现示例
2020/07/09 Python
用python写一个带有gui界面的密码生成器
2020/11/06 Python
CSS3之多背景background使用示例
2013/10/18 HTML / CSS
美国高端医师级美容产品电商:BeautifiedYou.com
2017/04/17 全球购物
Michael Kors加拿大官网:购买设计师手袋、手表、鞋子、服装等
2019/03/16 全球购物
洲际酒店集团英国官网:IHG英国
2019/07/10 全球购物
J2EE面试题集锦(附答案)
2013/08/16 面试题
党员先进性教育整改措施
2014/09/18 职场文书
2015毕业生自我评价范文
2015/03/02 职场文书
社区党员干部承诺书
2015/05/04 职场文书