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.
看效果:


猜你喜欢
- 之前用bash实现过(https://www.jb51.net/article/61943.htm),不过那个不能在windows下使用,所
- 微信小程序实现一个简单的select下拉框,供大家参考,具体内容如下用的是transform过渡,没用动画看看效果废话不多说,直接上代码wx
- 今天整理之前写的代码,发现在做数模期间写的用python实现的遗传算法,感觉还是挺有意思的,就拿出来分享一下。首先遗传算法是一种优化算法,通
- 介绍lambdaPython用于支持将函数赋值给变量的一个操作符 默认是返回的,所以不用再加return关键字,不然会报错result =
- 阅读上一章:Chapter 13 为文字指定样式Chapter 14 图片替换随着更多设计师与开发者开始使用标准(特别是CSS),每天都会有
- 由于计算机软件的非法复制,通信的泄密、数据安全受到威胁。一般为了安全,会要求将数据库名称、密码等信息进行加密。所以加密在开发过程中是经常使用
- 前言最近遇到一个需求,有几十个Excel,每个的字段都不一样,然后都差不多是第一行是表头,后面几千上万的数据,需要把这些Excel中的数据全
- 目录01 all or any02 dir03 列表(list)推导式04 pprint05 repr06 sh07 Type hints0
- 一.实现思路本文讲解如何使用python实现一个简单的模板引擎, 支持传入变量, 使用if判断和for循环语句, 最终能达到下面这样的效果:
- <% Rem Rem ## 在线升级类声明 Class Cls_oUpdate
- 本文实例为大家分享了python实现简单计算器功能的具体代码,供大家参考,具体内容如下效果如图:主要思路:用列表保存按下的键,按下等于,转换
- 1、简介APScheduler是一个 Python 定时任务框架,使用起来十分方便。提供了基于日期、固定时间间隔以及 crontab 类型的
- if exists (select * from dbo.sysobjects where id = object_id(N'[db
- 创建新项目,及应用django-admin startproject myprojcd myprojpython manage.py sta
- 在导入Python模块时,我们可以用import os也可以用from os import *当然,不推荐第二种方法,这样,会导入太多的os
- cooper谈到用户的视觉路径一般是:从上到下,从左到右。好的视觉设计路径应该是顺应这样的用户习惯,糟糕的设计会让用户无所适从,焦点到处都是
- 本文实例讲述了Codeigniter发送邮件的方法。分享给大家供大家参考。具体分析如下:Codeigniter的邮件发送支持一下特性:Mul
- 一、匹配版本基于Camunda 7.16.0 + Springboot 2.5.8首先我们去官网找到camunda7.16对应的spring
- 近日一直在折腾vps ,刚刚碰到在搬移wordpress过程中导入数据库的时候。碰到了 #1062 – Duplicate entry
- 一、为什么要包管理默认Go的第三方包都是放在Gopath的src目录下,而且这些包都没有版本号的概念,这样的可能会出现一些问题。举个例子:当