飘逸的python - 代码即文档docstring

什么是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.

看效果:

版权声明:本文为博主原创文章,未经博主允许不得转载。

时间: 2024-10-12 15:50:27

飘逸的python - 代码即文档docstring的相关文章

python+selenium自动化软件测试(第12章):Python读写XML文档

XML 即可扩展标记语言,它可以用来标记数据.定义数据类型,是一种允许用户对自己的标记语言进 行定义的源语言.xml 有如下特征: 首先,它是有标签对组成:<aa></aa> 标签可以有属性: <aa id=’123’></aa> 标签对可以嵌入数据: <aa>abc</aa>Python对XML文档读写常用有几个模块: (1) xml.etree.ElementTree ElementTree就像一个轻量级的DOM,具有方便友好的A

用Python做SVD文档聚类---奇异值分解----文档相似性----LSI(潜在语义分析)

转载请注明出处:电子科技大学EClab——落叶花开http://www.cnblogs.com/nlp-yekai/p/3848528.html SVD,即奇异值分解,在自然语言处理中,用来做潜在语义分析即LSI,或者LSA.最早见文章 An introduction to latent semantic analysis SVD的有关资料,从很多大牛的博客中整理了一下,然后自己写了个python版本,放上来,跟大家分享- 关于SVD的讲解,参考博客 本文由LeftNotEasy发布于http:

Openstack python api 学习文档

Openstack python api 学习文档 转载请注明http://www.cnblogs.com/juandx/p/4953191.html 因为需要学习使用api接口调用openstack,所以上一篇写了一些使用openstack的纯api调用的方法, 但是openstack还提供了更好的python的api,只需要python的包即可,感觉更好使用. 对于compute的api,包是放在了/usr/lib/python2.7/site-packages/novaclient/目录,

python解析PDF文档

1.安装 pip install pdfminer3k 2.  python读取PDF文档代码分析 PDF格式不是规范格式. 尽管它被叫做"PDF文档", 但并不像word或者html文档.PDF的表现更像一张图片.PDF更像是在一张纸的各个准确的位置上把内容都摆放出来.大部分情况下,没有逻辑结构,比如句子或段落,并且不能自适应页面大小的调整.PDFMiner尝试通过猜测它们的布局来重建它们的结构,但是不保证一定能工作.我知道这样很难看,但是,PDF确实不够规范. 下面这个图片是使用流

Python处理Excel文档(xlrd, xlwt, xlutils)

简介 xlrd,xlwt和xlutils是用Python处理Excel文档(*.xls)的高效率工具.其中,xlrd只能读取xls,xlwt只能新建xls(不可以修改),xlutils能将xlrd.Book转为xlwt.Workbook,从而得以在现有xls的基础上修改数据,并创建一个新的xls,实现修改. (以下属性或方法并非全部,需要更多属性请参看文档:建议先参考文末Demo,再深入了解) xlrd Book(class) 由xlrd.open_work("example.xls"

python 分词计算文档TF-IDF值并排序

文章来自于我的个人博客:python 分词计算文档TF-IDF值并排序 该程序实现的功能是:首先读取一些文档,然后通过jieba来分词,将分词存入文件,然后通过sklearn计算每个分词文档中的tf-idf值,再将文档排序输入一个大文件中 依赖包: sklearn jieba 注:此程序参考了一位同行的程序后进行了修改 # -*- coding: utf-8 -*- """ @author: jiangfuqiang """ import os

python 解析html文档模块HTMLPaeser

python中,有三个库可以解析html文本,HTMLParser,sgmllib,htmllib.他们的实现方法不通,但功能差不多.这三个库中 提供解析html的类都是基类,本身并不做具体的工作.他们在发现的元件后(如标签.注释.声名等),会调用相应的函数,这些函数必须重载,因为基类中不作处理. 用Python中自带的HTMLPaeser模块,解析下面的HTMl文件 要求:1.获取到每一个漏洞的名称,CVE号,风险值 2.显示每一个漏洞单独显示,不要堆叠在一起 3.只获取高风险的漏洞 <htm

python 解析docx文档的方法,以及提取插入的文本对象和图片

首先安装docx模块,通过pip install docx或者在docx官方链接上下载安装都可以 下面来看下如何解析docx文档:文档格式如下 有3个部分组成 1 正文:text文档 2 一个表格. 3一个插入的文件对象.4 一个图片 这4个部分是我们在docx文档中最常见的几种格式.解析代码如下 import docx def docx_try():     doc=docx.Document(r'E:\py_prj\test.docx')     for p in doc.paragraph

python 函数的文档字符串 docstrings

函数体的第一行可以是一个可选的字符串文本:此字符串是该函数的文档字符串,或称为docstring.(更多关于 docstrings 的内容可以在 文档字符串一节中找到.)有工具使用 docstrings 自动生成在线的或可打印的文档,或者让用户在代码中交互浏览:在您编写的代码中包含 docstrings 是很好的做法,所以让它成为习惯吧.