Python 小技巧 056：Python 的 pydoc（2. 自动生成文档）

zltzlt

Python pydoc 自动生成文档

当你编写准备发布到 Pypi 的模块时，通常要编写文档让其他人明白你的模块怎么用，可是文档比代码更占空间。Python 提供的工具 pydoc 也可以用于自动为你的模块生成文档。

下面是一个简单的例子：

创建一个 demo.py 文件，该模块模拟 timeit 测量代码执行所需的时间：

# -*- coding: utf-8 -*-

"""测量代码执行时间的模块"""

from time import perf_counter


def timeit(stmt="pass") -> float:
    """测量指定代码段执行所需的时间"""
    start = perf_counter()
    exec(stmt)
    return perf_counter() - start

之后打开 cmd，切换到模块目录，执行 python -m pydoc demo（模块名不需要加后缀 .py），打印的内容就是 Pydoc 为你生成的文档（除了第一行 Help on module demo:）：

> python -m pydoc demo
Help on module demo:

NAME
    demo - 测量代码执行时间的模块

FUNCTIONS
    perf_counter(...)
        perf_counter() -> float

        Performance counter for benchmarking.

    timeit(stmt='pass') -> float
        测量指定代码段执行所需的时间

FILE
    E:\demo.py

将文档拷贝到模块中，完事Pydoc 模块的确会让你事半功倍。

# -*- coding: utf-8 -*-

"""
NAME
    demo - 测量代码执行时间的模块

FUNCTIONS
    perf_counter(...)
        perf_counter() -> float

        Performance counter for benchmarking.

    timeit(stmt='pass') -> float
        测量指定代码段执行所需的时间
"""

from time import perf_counter


def timeit(stmt="pass") -> float:
    """测量指定代码段执行所需的时间"""
    start = perf_counter()
    exec(stmt)
    return perf_counter() - start

Pydoc 还可以为你生成 HTML 文档。输入 python -m pydoc -w {模块名} 即可（在例子中是 python -m pydoc -w demo）：

> python -m pydoc -w demo
wrote demo.html

提示已经将文档写入 demo.html。让我们用浏览器打开 demo.html：



不错，排版勉强能接受

xlhhh

666

_2_

这……html有点难以接受