Python中的多行注释文档编写风格汇总
作者:mattkang 发布时间:2023-05-05 02:41:18
什么是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.
看效果:
猜你喜欢
- * 对子查询和Join进行了优化,包括对MyISAD和InnoB存储引擎分散范围内的批量索引访问。* 增加了 BACKUP DATABASE
- 我们日常用CSS布局的时候,关于图片背景,大部分的人都是一个背景一张图片的,怎么说呢?这是很标准的方法,但是这种普通制作方式下要保存大量图片
- newstudent.asp<script LANGUAGE=″vbscript″ RUNAT=″Server″&
- 可能是我“火星”了,不过在 空虚 的 Blog 中学到的一招。这个技巧的原理是利用 iframe 载入本机各盘符的根目录,然后判断 ifra
- 本文实例讲述了php版微信支付api.mch.weixin.qq.com域名解析慢原因与解决方法。分享给大家供大家参考,具体如下:微信支付a
- 本文实例讲述了PHP实现将科学计数法转换为原始数字字符串的方法,分享给大家供大家参考。具体实现代码如下:function NumToStr(
- 一个网站信息结构需要表现给用户看,这样用户才能知道当前是在哪儿,才有可能去猜测某个内容可能会在哪儿。如何表现网站的信息结构给用户呢?用导航。
- 一、请求扩展1.before_request作用: 类比django中间件中的process_request,在请求到来执行路由函数之前先执
- 写了网址规范化后,尚奇公司的柳先生建议再深入讨论一下301转向/重定向。下面就谈谈我所了解的301转向在搜索引擎优化方面的应用。什么是301
- 记录一次小白的tensorflow学习过程,也为有同样困扰的小白留下点经验。先说我出错和解决的过程。在做风格迁移实验时,使用预加载权重的VG
- 记录一下如何用python爬取app数据,本文以爬取抖音视频app为例。编程工具:pycharmapp抓包工具:mitmproxyapp自动
- 原理:自定义javascript中的oncontextmenu事件,然后使用div层模拟菜单。知道了这个原理结合美工相信你可以做出很漂亮的自
- Cookies,有些人喜欢它们,有些人憎恨它们。但是,很少有人真正知道如何使用它们。现在你可以成为少数人中的成员-可以自傲的Cookie 大
- CSS 文件的大小和所引起的 HTTP 的请求数是 CSS 性能的最关键因素回流(reflow)和渲染时间(非常!)没那么重要副本(dupl
- 常用的四种SQL命令:1.查询数据记录(Select)语法:Select 字段串行 From table Where 字段=内容例
- 如果机房马上要关门了,或者你急着要和MM约会,请直接跳到第四个自然段。以下叙述的脚本包括服务器端脚本和客户端的脚本,服务器端脚本指在服务器上
- 数据库复制就是由两台服务器,主服务器和备份服务器,主服务器修改后,备份服务器自动修改,在以前的文章中已经做了详细的说明,这里就不在重复.使用
- 由于车票难抢,有时需要的车票已经售空,而我们需要捡漏,便可使用这个脚本。具体实现了,自动查询某一车票的余票数量,当数量产生变化时,将自动发送
- ul设置浮动后不能自适应高度,也就是不能撑开父容器,不能自适应内容的高度。解决方法是在ul结束标签前加个清除浮动。 &
- PHP addcslashes() 函数实例在字符 "W" 前添加反斜杠:<?php $str = addcsla