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并发编程之多进程、多线程、异步和协程详解
Oct 28 Python
TensorFlow实现随机训练和批量训练的方法
Apr 28 Python
python得到电脑的开机时间方法
Oct 15 Python
Python设计模式之状态模式原理与用法详解
Jan 15 Python
Python实现求两个数组交集的方法示例
Feb 23 Python
python文档字符串(函数使用说明)使用详解
Jul 30 Python
Python爬虫学习之翻译小程序
Jul 30 Python
Python简易版停车管理系统
Aug 12 Python
浅谈TensorFlow之稀疏张量表示
Jun 30 Python
Python中Selenium库使用教程详解
Jul 23 Python
Django怎么在admin后台注册数据库表
Nov 14 Python
python如何发送带有附件、正文为HTML的邮件
Feb 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
smarty实例教程
2006/11/19 PHP
php管理nginx虚拟主机shell脚本实例
2014/11/19 PHP
PHP实现Google plus的好友拖拽分组效果
2016/10/21 PHP
laravel实现分页样式替换示例代码(增加首、尾页)
2017/09/22 PHP
PHP封装的mysqli数据库操作类示例
2019/02/16 PHP
js几个验证函数代码
2010/03/25 Javascript
一段批量给页面上的控件赋值js
2010/06/19 Javascript
13个绚丽的Jquery 界面设计网站推荐
2010/09/28 Javascript
js截取小数点后几位的写法
2013/11/14 Javascript
通过js来制作复选框的全选和不选效果
2014/05/22 Javascript
jQuery中mouseover事件用法实例
2014/12/26 Javascript
javascript获取重复次数最多的字符
2015/07/08 Javascript
浅谈jquery的map()和each()方法
2016/06/12 Javascript
jQuery模拟完美实现经典FLASH导航动画效果【附demo源码下载】
2016/11/09 Javascript
JavaScript cookie详解及简单实例应用
2016/12/31 Javascript
详解AngularJS1.6版本中ui-router路由中/#!/的解决方法
2017/05/22 Javascript
Ajax高级笔记 JavaScript高级程序设计笔记
2017/06/22 Javascript
解决微信二次分享不显示摘要和图片的问题
2017/08/18 Javascript
实例讲解JavaScript截取字符串
2018/11/30 Javascript
node+multer实现图片上传的示例代码
2020/02/18 Javascript
[01:43]3.19DOTA2发布会 三代刀塔人第三代
2014/03/25 DOTA
[01:59]DOTA2首部纪录片《Free to play》预告片
2014/03/12 DOTA
Python实现将数据库一键导出为Excel表格的实例
2016/12/30 Python
Python操作MongoDB详解及实例
2017/05/18 Python
教你用一行Python代码实现并行任务(附代码)
2018/02/02 Python
Python字符串、整数、和浮点型数相互转换实例
2018/08/04 Python
在Python中画图(基于Jupyter notebook的魔法函数)
2019/10/28 Python
13个Pandas实用技巧,助你提高开发效率
2020/08/19 Python
使用Python webdriver图书馆抢座自动预约的正确方法
2021/03/04 Python
婴儿地球:Baby Earth
2018/12/25 全球购物
英国美术用品购物网站:Cass Art
2019/10/08 全球购物
俄罗斯一家时尚女装商店:Charuel
2019/12/04 全球购物
自荐信格式
2013/12/01 职场文书
电视节目策划方案
2014/05/16 职场文书
怀孕辞职信怎么写
2015/02/28 职场文书
加班费申请报告
2015/05/15 职场文书