关闭

飘逸的python - 代码即文档docstring

标签: python文档docstringsphinx
8644人阅读 评论(0) 收藏 举报
分类:

什么是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.
看效果:
这里写图片描述

2
0
查看评论
发表评论
* 以上用户言论只代表其个人观点,不代表CSDN网站的观点或立场

Python docstring文档字符串

使用DocStrings Python有一个很奇妙的特性,称为 文档字符串,它通常被简称为 docstrings 。DocStrings是一个重要的工具,由于它帮助你的程序文档更加简单易懂,你应该尽...
  • jiyanfeng1
  • jiyanfeng1
  • 2012-10-27 06:10
  • 10848

Python对象的文档字符串(DocString):__doc__的写法和输出方法

Python有个特性叫做文档字符串,即DocString,这个特性可以让你的程序文档更加清晰易懂,在python的系统文件里,也都在使用这个特性。因此推荐每个Python爱好者都使用它。       ...
  • houbin01
  • houbin01
  • 2016-11-24 22:11
  • 1592

Python DocString特性

#!/usr/bin/python #Filename:func_doc.py def printMax(x,y): '''Prints the maximum of two numbers ...
  • gukesdo
  • gukesdo
  • 2011-11-27 20:08
  • 3447

Python编码规范(PEP8)及奇技淫巧(不断更新)

Python 2.7前言 从很多地方搬运+总结,以后根据这个标准再将python的一些奇技淫巧结合起来,写出更pythonic的代码~ PEP8 编码规范英文原版请点击这里以下是@bobo的整理,...
  • MrLevo520
  • MrLevo520
  • 2017-04-04 19:18
  • 1369

Python随笔之文档字符串(DocStrings)

在Python中有一个奇妙的特性,文档字符串,又称为DocStrings。用它可以为我们的模块,类,函数添加说明性的文字,使程序易读易懂,更重要的是可以通过Python自带的标准方法将这些描述性文字信...
  • chris_mao
  • chris_mao
  • 2011-09-07 13:34
  • 8324

Python中的Doc String 函数描述

将文档写在程序里,是LISP中的一个特色,Python也借鉴过。每个函数都是一个对象,每个函数对象都是有一个__doc__的属性,函数语句中,如果第一个表达式是一个string,这个函数的__doc_...
  • liuguiyangnwpu
  • liuguiyangnwpu
  • 2013-07-21 10:13
  • 2935

该死的“代码就是文档”

我在《专业嵌入式软件开发》一书中指出,编写言简意骇的文档是实施高质高效软件开发的关键要素之一。在此结合自己的工作体会,再谈一谈软件开发活动中文档的重要性。切入正题之前,先让我们浏览二个工作场景。 ...
  • hzliyun
  • hzliyun
  • 2012-08-18 10:54
  • 17390

用epydoc从python代码中直接生成文档

在一个大的项目里,或在接手别人项目时才知道文档是多么重要,以后写代码时也要多写写文档,实在没有文档,注释也要多写写。今天晚上本来是想看看pynotify的,没文档,需要自己生成,这一下就让我想到,如果...
  • largetalk
  • largetalk
  • 2011-11-08 23:17
  • 6711

使用DocStrings为python函数添加注释

有过Java或AS3编程经验的码农,不难有zh
  • mekaoyou
  • mekaoyou
  • 2014-04-11 16:02
  • 2224

Python 中调用函数的Docstring

def printmax(x,y):     '''You are a girl.     don't your.'''     x=int(x)   ...
  • tuchixiong
  • tuchixiong
  • 2014-11-06 10:07
  • 243
    个人资料
    • 访问:716119次
    • 积分:7863
    • 等级:
    • 排名:第3085名
    • 原创:137篇
    • 转载:0篇
    • 译文:0篇
    • 评论:115条
    公告
    联系邮箱:160824@qq.com
    博客专栏
    文章分类
    最新评论