Python中的多行注释文档编写风格汇总

什么是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.
看效果：

赞 (0)

相关推荐

  • python实现的正则表达式功能入门教程【经典】

    本文讲述了python实现的正则表达式功能.分享给大家供大家参考,具体如下: 前文: 首先,什么叫正则表达式(Regular Expression)? 例如我们要判断字符串"adi_e32fv,Ls"里面是否含有子串"e32f",又例如我们在一个含百万个姓名的txt文件中找姓"王",名字以"五"结尾的名字,然后打印出来.结果为:"王五"."王小五"."王大五".&qu

  • Python实现删除Android工程中的冗余字符串

    Android提供了一套很方便的进行资源(语言)国际化机制,为了更好地支持多语言,很多工程的翻译往往会放到类似crowdin这样的平台上.资源是全了,但是还是会有一些问题. 哪些问题 以下使用一些语言进行举例.其中values为工程默认的资源. 1.某语言的资源和某语言限定区域的资源之间.如values-fr-rCA存在于values-fr相同的字符串,这种表现最为严重. 2.某语言的资源和默认的资源之间.values-fr存在与values相同的字符串,可能原因是由于values-fr存在未翻

  • Python中使用strip()方法删除字符串中空格的教程

    strip()方法返回所有字符从开始及字符串的末尾(默认空格字符)被去除后的字符串的一个副本. 语法 以下是strip()方法的语法: str.strip([chars]); 参数 chars -- 字符-从开始或结束的字符串被删除去除. 返回值 此方法返回所有字符从开始及字符串的末尾(默认空格字符)被去除后的字符串的一个副本. 例子 下面的例子显示了strip()方法的使用. #!/usr/bin/python str = "0000000this is string example....w

  • Python基于正则表达式实现检查文件内容的方法【文件检索】

    本文实例讲述了Python基于正则表达式实现检查文件内容的方法分享给大家供大家参考,具体如下: 这个是之前就在学python,欣赏python的小巧但是功能强大,是连电池都自带的语言.平时工作中用Java ,觉得python在日常生活中比java用处要大,首先语法没那么复杂,特别是io的操作,java里要写一大坨没关的代码.还有就是不用编译,而且linux系统默认都会自带. 这次遇到的问题是工作当中想要迁移一个系统中的一个模块,这个时候需要评估模块里的代码有没有对其他代码强依赖,就是有没有imp

  • Python实现多行注释的另类方法

    Python程序的注释感觉很不合群,对于习惯了使用/**/多行注释的人来说,到Python中只能使用#号进行单行注释很痛苦. 复制代码 代码如下: # 这里是单行注释 # a = 50 # b = 10 # c = 10 其实我们可以通过多行文本定义的格式实现多行注释: 复制代码 代码如下: """     # 这里是多行注释     a = 50     b = 10     c = 10 """ 这个方法感觉还不错,跟/**/多行注释用起来没

  • python正则表达式中的括号匹配问题

    问题: m = re.findall('[0-9]*4[0-9]*', '[4]') 可以匹配到4. m = re.findall('([0-9])*4([0-9])*', '[4]') 匹配不到4. 这是为什么呢?PS,这个是一个简化的说明,我要用的正则比这个复杂,所以要用到(),表示一个序列的匹配. 补充一点,我放在notepad++中用的时候,两种写法都能匹配出来,不知道为什么python中就不行了. 答案: python的正则中用()会进行匹配,所以返回结果是['',''],就是两个()

  • Python文件去除注释的方法

    本文实例讲述了Python文件去除注释的方法.分享给大家供大家参考.具体实现方法如下: #!/usr/bin/python # -*- coding: GBK -*- #writer:xmnathan #py文件去注释 import re import os import ConfigParser Python='CleanNote' def ReadIni(path,section,option):#文件路径,章节,关键词 #读取ini cf=ConfigParser.ConfigParser

  • Python使用中文正则表达式匹配指定中文字符串的方法示例

    Python使用中文正则表达式匹配指定中文字符串的方法示例

    本文实例讲述了Python使用中文正则表达式匹配指定中文字符串的方法.分享给大家供大家参考,具体如下: 业务场景: 从中文字句中匹配出指定的中文子字符串 .这样的情况我在工作中遇到非常多, 特梳理总结如下. 难点: 处理GBK和utf8之类的字符编码, 同时正则匹配Pattern中包含汉字,要汉字正常发挥作用,必须非常谨慎.推荐最好统一为utf8编码,如果不是这种最优情况,也有酌情处理. 往往一个具有普适性的正则表达式会简化程序和代码的处理,使过程简洁和事半功倍,这往往是高手和菜鸟最显著的差别.

  • Python正则表达式匹配HTML页面编码

    html页面一般都会指定一个编码,如何获取到是处理html页面的第一步,因为错误的编码必然带来后面处理的问题.这里我用python的正则表达式写了个: import re a = ["<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />", '<meta http-equiv=Content-Type content="text/ht

  • Python 匹配任意字符（包括换行符）的正则表达式写法

    想使用正则表达式来获取一段文本中的任意字符,写出如下匹配规则: (.*) 结果运行之后才发现,无法获得换行之后的文本.于是查了一下手册,才发现正则表达式中,"."(点符号)匹配的是除了换行符"\n"以外的所有字符. 以下为正确的正则表达式匹配规则: ([\s\S]*) 同时,也可以用 "([\d\D]*)"."([\w\W]*)" 来表示. Web技术之家_www.waweb.cn 在文本文件里, 这个表达式可以匹配所有的英文

  • Python删除Java源文件中全部注释的实现方法

    本文实例讲述了Python删除Java源文件中全部注释的实现方法.分享给大家供大家参考,具体如下: 同事想删除一个Java项目中的全部注释,让我帮忙想想办法. 没找不到合适工具,就写了这个脚本,遍历指定目录,查找*.java文件,删除其中/* */之间,及// 至行末的内容. (用之前要改改其中的路径): #!D:\Python32 # 过滤JAVA程序中的注释 # 如果字符串中有注释符号的话会有问题. import os import re import io # 改这个目录!!! top_d

随机推荐