python pydoctor

# Python Pydoctor：一个被低估的文档生成工具

它是什么

Pydoctor这个名字在Python社区里其实有点小众。它是由Twisted项目组开发的API文档生成工具，专门用来从Python源代码中提取信息，生成结构化的API文档。和Sphinx那种什么都想管的“全家桶”不同，Pydoctor只做一件事：解析Python对象模型，生成清晰的API参考文档。

这东西的历史可以追溯到Twisted项目早期。Twisted这个网络编程框架本身代码量巨大、继承关系复杂，普通的文档工具根本搞不定它的对象模型。于是他们自己动手写了一个，后来发现其他项目也用得上，就独立出来了。现在它是一个独立的开源项目，GitHub上能找到。

它能做什么

想象一下你有个庞大的代码库，里面有几十个模块、几百个类、上千个方法。你写了一大堆docstring，但没有人知道你的代码里到底暴露了什么API，哪些是公开接口，哪些是内部实现。Pydoctor就是来解决这个问题的。

它最拿手的是处理复杂的继承关系。比如说，你有一个继承链很深的类体系，A继承B，B继承C，C又继承自D。Pydoctor能把这些继承关系画得清清楚楚，包括哪些方法是从哪个父类继承来的，哪些方法被子类重写了。这对于理解框架代码特别有用——很多时候你调用的方法根本不定义在当前类里，而是从某个遥远的基类继承的。

它还支持类型注解。现在Python的类型注解越来越普及，Pydoctor能识别这些注解，在生成的文档里显示参数和返回值的类型信息。如果你用typing模块写了复杂的类型定义，比如Union、Optional、List[Dict[str, int]]这种东西，它也能正确渲染。

另一个实用的功能是私有方法处理。Pydoctor默认只显示“公开”的API——也就是名字以一个下划线开头的私有方法会被隐藏。但你也可以配置让它显示私有成员，这对于内部文档或者代码审查很有用。

怎么使用

安装很简单，pip一句搞定：

pip install pydoctor

最基础的使用方式是直接指定要生成文档的目录：

pydoctor --docformat=epytext mypackage

这里指定了docstring格式。Pydoctor支持三种主流格式：epytext（Twisted自家的格式）、restructuredText和Google风格。推荐用Google风格，因为它写起来最直观，而且和现代Python社区的习惯一致。

如果需要生成包含多个包的文档：

pydoctor package_a package_b --docformat=google --project-name=MyProject --project-url=https://github.com/me/myproject

生成的文档默认放在apidocs目录下。它是一个静态网站，包含完整的导航树、搜索功能和类层次视图。

最佳实践

用了一段时间Pydoctor，总结出几条实用经验：

第一，给docstring写“类型”注解最好用Google风格。比如：

defconnect(host:str,port:int=8080)->Connection:"""建立网络连接 Args: host: 主机名或IP地址 port: 端口号，默认8080 Returns: Connection对象，可用于后续通信 Raises: ConnectionError: 如果连接失败 """

这种写法Pydoctor识别得很好，生成的文档清晰又专业。

第二，合理使用__all__。Pydoctor默认会根据__all__列表来判断哪些是公开API。如果你在模块里定义了__all__ = ["PublicClass", "public_function"]，那只有这些才会出现在文档里。对于大型项目来说，这是个好习惯，可以避免把内部实现暴露给用户。

第三，注意继承文档的继承。Pydoctor有一个智能特性：如果子类没有写docstring，它会自动继承父类的文档。但如果你重写了方法，最好还是写一下，哪怕只是简单写一句“重写自父类”。这样生成文档时，读者不会被误导。

第四，配置文件的妙用。Pydoctor支持通过配置文件来定制很多行为。比如可以指定哪些目录要排除、哪些模块要忽略、生成的文档标题是什么。建立一个pydoctor.ini文件放在项目根目录：

[pydoctor] project-name = My Awesome Library project-url = https://github.com/me/myproject source-url = https://github.com/me/myproject/blob/master/ docformat = google

这样每次运行就简单了：

pydoctor mypackage

和同类技术对比

说到文档生成，大家最先想到的肯定是Sphinx。它确实是Python文档领域的霸主，但两者定位不同。

Sphinx更像是“通用文档系统”，什么都能干：写教程、写研讨会记录、发布博客。它有一个庞大的插件生态，支持生成PDF、LaTeX、epub等格式。但代价是配置复杂、启动慢、而且生成的文档结构受限于ReST语法。

Pydoctor则是“专为API文档而生”。它启动快，配置简单，生成的API参考文档非常“干净”，没有多余的装饰。如果你只是想给你的开源库生成一个类似Python官方文档那样的API参考页面，Pydoctor可能比Sphinx省事得多。

还有一个值得提的是pdoc3。它也是个轻量级的文档生成工具，但和Pydoctor的思想略有不同。pdoc3更强调“所见即所得”——你写的docstring直接渲染成文档，不做额外的结构抽取。Pydoctor则会深入分析代码结构，比如找出所有继承关系、所有抽象方法、所有接口实现，然后把这些信息呈现在文档里。这种深度分析对于那些代码结构复杂的项目尤其有用。

另一个经常被比较的是mkdocstrings，它是MkDocs的一个插件，专注于API文档生成。它也很轻量、集成度高，特别适合那些已经用MkDocs搭建文档的项目。但它的核心功能依赖于外部解析器（比如griffe），不如Pydoctor那样自给自足。

总结来说，Pydoctor最适合的场景是：你有一个复杂的Python项目，继承关系多、接口多，你需要生成干净、结构清晰的API参考文档。它不和Sphinx抢通用文档的市场，而是在API文档这块深耕细作。如果你正在维护一个大型库或者框架，值得一试。