## pdoc & Python 文档工具 - Hacker News 摘要 一个 Hacker News 讨论围绕 **pdoc** 展开，这是一个轻量级的 Python API 文档生成工具。用户称赞 pdoc 的简单性，尤其是在小型项目中，它易于使用且能与 GitHub 工作流集成。 然而，随着项目规模扩大，**MkDocs**（带有 Material 主题）因其更丰富的功能和部署选项而受到推荐。一个插件，**mkdocstrings**，允许 MkDocs 从代码注释中自动生成文档，弥合了这两个工具之间的差距。 对话还涉及文档风格——具体来说，文档字符串相对于变量声明的位置。pdoc 独特地读取赋值语句后跟文档字符串，这一设计选择受到用户辩论，他们通常更喜欢将文档字符串放在声明*上方*，类似于 Rust 的方法。pdoc 维护者解释说，这个选择源于与 Python 函数文档字符串的一致性，并避免歧义。 最后，用户讨论了自动生成文档与更详细的手写文档（例如使用 Sphinx）之间的平衡，并提到了正在进行的努力，以提高分叉稳定性以及文档工具之间的链接检查。