python:为自定义包写doc实战

最近在看webpy的源码，发现其模块的help()输出非常漂亮：

image.png

作为一个python初学者，度娘了一下docstring的具体用法，大部分都说得很简单，除了_doc_属性以及单行、多行注释以外几乎没什么详细和系统的介绍docstring的写法。作为程序员必备的基本能力之一，我就在这里练练如何写好docstring，并将其过程记录下来以备大家参考。

如何看webpy的docstring

1. 下载源码
   webpy的源码

2.help输出（Linux）

ln -s 源码中的web目录地址 .
python -c "import web;help(web)"

参考材料：help()的实现

help()源码地址

实战开始：环境准备

1.创建测试包

image.png

其中__init__.py是个空文件

2.help输出

python -c "import test_mod;help(test_mod)"

image.png

各种SECTION及对应的使用方法

1.NAME与DESCRIPTION

修改__init__.py（左边）并观察help的输出（右边）：

123.png

注：第三种情况中第二行为空行

2.PACKAGE CONTENTS（自生成）

123.png

3.CLASSES（自生成）

123.png

对于外部能看到的class，help()会输出相应的信息
图注：
1.类的继承关系
2.类的描述

3.DATA、FUNCTIONS（自生成）

123.png

3.VERSION、DATE、AUTHOR、CREDITS

123.png