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中内置的itertools模块
Apr 29 Python
在Linux系统上安装Python的Scrapy框架的教程
Jun 11 Python
Python实现线程池代码分享
Jun 21 Python
Python3解决棋盘覆盖问题的方法示例
Dec 07 Python
python 实现数组list 添加、修改、删除的方法
Apr 04 Python
Pycharm2017版本设置启动时默认自动打开项目的方法
Oct 29 Python
Pandas聚合运算和分组运算的实现示例
Oct 17 Python
Django实现celery定时任务过程解析
Apr 21 Python
使用matlab 判断两个矩阵是否相等的实例
May 11 Python
DataFrame 数据合并实现(merge,join,concat)
Jun 14 Python
Python 的 __str__ 和 __repr__ 方法对比
Sep 02 Python
python如何用matplotlib创建三维图表
Jan 26 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+AJAX实现无刷新注册(带用户名实时检测)
2007/01/02 PHP
PHP中“简单工厂模式”实例代码讲解
2012/09/04 PHP
php array_multisort 对数组进行排序详解及实例代码
2016/10/27 PHP
php常用数组函数实例小结
2016/12/29 PHP
laravel5.6 框架邮件队列database驱动简单demo示例
2020/01/26 PHP
jquery+ajax每秒向后台发送请求数据然后返回页面的代码
2011/01/17 Javascript
判断一个变量是数组Array类型的方法
2013/09/16 Javascript
node.js中的fs.lchownSync方法使用说明
2014/12/16 Javascript
JavaScript中Form表单技术汇总(推荐)
2016/06/26 Javascript
Vue 过渡(动画)transition组件案例详解
2017/01/22 Javascript
JS 实现banner图片轮播效果(鼠标事件)
2017/08/04 Javascript
在 Angular 中使用Chart.js 和 ng2-charts的示例代码
2017/08/17 Javascript
Vue 多层组件嵌套二种实现方式(测试实例)
2017/09/08 Javascript
JSON 数据格式详解
2017/09/13 Javascript
微信小程序日历/日期选择插件使用方法详解
2018/12/28 Javascript
vue实现数字动态翻牌的效果(开箱即用)
2019/12/08 Javascript
Vue的状态管理vuex使用方法详解
2020/02/05 Javascript
vue实现购物车功能(商品分类)
2020/04/20 Javascript
图解JS原型和原型链实现原理
2020/09/15 Javascript
Python base64编码解码实例
2015/06/21 Python
python利用pandas将excel文件转换为txt文件的方法
2018/10/23 Python
Python中asyncio模块的深入讲解
2019/06/10 Python
django框架cookie和session用法实例详解
2019/12/10 Python
Tensorflow之梯度裁剪的实现示例
2020/03/08 Python
python和c语言哪个更适合初学者
2020/06/22 Python
python 通过pip freeze、dowload打离线包及自动安装的过程详解(适用于保密的离线环境
2020/12/14 Python
html5指南-7.geolocation结合google maps开发一个小的应用
2013/01/07 HTML / CSS
中国宠物用品商城:E宠商城
2016/08/27 全球购物
大学生职业规划范文:象牙塔生活的四年计划
2014/01/14 职场文书
机关门卫制度
2014/02/01 职场文书
三行辞职书范文
2015/02/26 职场文书
求职信内容一般写什么?
2015/03/20 职场文书
Golang标准库syscall详解(什么是系统调用)
2021/05/25 Golang
python常见的占位符总结及用法
2021/07/02 Python
Vue.Draggable实现交换位置
2022/04/07 Vue.js
MySQL创建管理KEY分区
2022/04/13 MySQL