Pdoc：轻量级生成 API 文档

pdoc 是一个轻量级的库，专注于为 Python 项目生成 API 文档。 它通过扫描指定的模块和包，自动提取文档字符串，快速转化为易于浏览的 HTML 文档。这项技术尤其适用于需要快速生成文档的现代 Python 项目。 与市面上其他文档生成库例如 Sphinx 相比，pdoc 的特色在于其轻量级和易用性。 开发者无需过多配置，便可以得到整洁的 API 文档，将时间更多地投入到代码的编写上。 但如果项目需要更丰富的用户手册或教程编写功能，那么可能需要考虑其它如 Sphinx 的工具。 项目地址：https://github.com/mitmproxy/pdoc

安装

pdoc 支持 Python 3.6 以上版本，安装非常简便，只需一个 pip 命令：

pip install pdoc

基本用法

使用 pdoc，你只需要执行一个简单的命令即可生成你的项目文档：

pdoc your_python_module

或者，针对一个具体的文件，可以这样：

pdoc ./my_project.py

pdoc 还有内置的 web 服务器支持实时重新加载。如果你想查看 pdoc 自己的文档，可以运行：

pdoc pdoc

想查看支持的命令行选项，运行：

pdoc --help

或者，你可以访问官方文档[1]来获取更多信息。

Markdown 支持

pdoc 极大地简化了文档编写流程，它将文档视为普通的 Markdown 文件，让你更专注于内容的创作。

现代 Python 语言特性

pdoc 对现代 Python 3 的类型注解和其它特性提供了一流的支持。

自动化和便捷性

pdoc 能自动链接你文档字符串中的标识符到对应文档。它也会理解 numpydoc 和 Google 风格的字符串。

完美的继承

pdoc 会通过继承来解析类型注解和 docstrings。

高级功能

pdoc 的高级功能包括：

• 自定义 HTML 模板支持
• 自动尝试解析类型注释字符串字面量作为前向引用
• 使用继承来解析类成员的类型注释和文档字符串。

对于有着更复杂文档需求的开发者，pdoc 提供了生成独立 HTML 文档的能力，而无需其他依赖。

在线预览

有时你可能需要直接预览生成的文档。pdoc 提供了在线预览的功能，只需一个命令：

pdoc -o ./html pdoc

生成的网站示例可以在这里查看官方文档。

示例

"""
A small `pdoc` example.
"""

class Dog:
    """"""
    name: str
    """The name of our dog."""
    friends: list["Dog"]
    """The friends of our dog."""

    def __init__(self, name: str):
        """Make a Dog without any friends (yet)."""
        self.name = name
        self.friends = []

    def bark(self, loud: bool = True):
        """*woof*"""

    @property
    def age(self) -> int:
        """*3 years old*"""        

pdoc ./snake.py

自定义网站 logo

pdoc ./snake.py --logo "https://placedog.net/300?random"

参考资料 [1] 官方文档: https://pdoc.dev/docs/pdoc.html [2] numpydoc: https://www.osgeo.cn/numpy/docs/howto_document.html [3] docstrings: https://www.runoob.com/w3cnote/python-docstrings.html