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 制作图片转pdf工具
Jan 30 Python
使用Python中的cookielib模拟登录网站
Apr 09 Python
Python的Django中django-userena组件的简单使用教程
May 30 Python
详解Python多线程
Nov 14 Python
vscode 远程调试python的方法
Dec 01 Python
numpy中以文本的方式存储以及读取数据方法
Jun 04 Python
Python爬虫——爬取豆瓣电影Top250代码实例
Apr 17 Python
Python一行代码实现快速排序的方法
Apr 30 Python
python整合ffmpeg实现视频文件的批量转换
May 31 Python
pytorch 使用加载训练好的模型做inference
Feb 20 Python
Python 安装 virturalenv 虚拟环境的教程详解
Feb 21 Python
浅谈Python中的字符串
Jun 10 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 用sock技术发送邮件的函数
2007/07/21 PHP
Zend Studio去除编辑器的语法警告设置方法
2012/10/24 PHP
php延迟静态绑定实例分析
2015/02/08 PHP
PHP排序算法之快速排序(Quick Sort)及其优化算法详解
2018/04/21 PHP
PHP的图像处理实例小结【文字水印、图片水印、压缩图像等】
2019/12/20 PHP
jquery插件如何使用 jQuery操作Cookie插件使用介绍
2012/12/15 Javascript
js 验证密码强弱的小例子
2013/03/21 Javascript
jquery select多选框的左右移动 具体实现代码
2013/07/03 Javascript
jQuery 中DOM 操作详解
2015/01/13 Javascript
js获得当前系统日期时间的方法
2015/05/06 Javascript
JS获取IMG图片高宽的简单实例
2016/05/17 Javascript
JavaScript数据类型和变量_动力节点Java学院整理
2017/06/26 Javascript
js图片放大镜实例讲解(必看篇)
2017/07/17 Javascript
webpack将js打包后的map文件详解
2018/02/22 Javascript
layer的prompt弹出框,点击回车,触发确定事件的方法
2019/09/06 Javascript
layui表格内放置图片,并点击放大的实例
2019/09/10 Javascript
Python模仿POST提交HTTP数据及使用Cookie值的方法
2014/11/10 Python
用Python编写生成树状结构的文件目录的脚本的教程
2015/05/04 Python
Python根据区号生成手机号码的方法
2015/07/08 Python
用python生成1000个txt文件的方法
2018/10/25 Python
python画图--输出指定像素点的颜色值方法
2019/07/03 Python
关于pandas的离散化,面元划分详解
2019/11/22 Python
浅谈ROC曲线的最佳阈值如何选取
2020/02/28 Python
python的Jenkins接口调用方式
2020/05/12 Python
wordpress添加Html5的表单验证required方法小结
2020/08/18 HTML / CSS
美国现代家具购物网站:LexMod
2019/01/09 全球购物
父亲的菜园教学反思
2014/02/13 职场文书
建筑结构施工专业推荐信
2014/02/21 职场文书
企业承诺书格式
2014/05/21 职场文书
工程造价专业求职信
2014/07/17 职场文书
个人公司授权委托书范本
2014/10/12 职场文书
社区母亲节活动总结
2015/02/10 职场文书
求职自荐信范文(优秀篇)
2015/03/27 职场文书
2015年行政人事工作总结
2015/05/21 职场文书
优秀教师工作总结2015
2015/07/22 职场文书
pandas时间序列之pd.to_datetime()的实现
2022/06/16 Python