使用 epydoc 记录公共全局函数

Question

我有一个包含多个全局函数和一个全局变量的模块。变量和一些函数遵循 Python 的“私有”命名约定，名称前导下划线。其他函数旨在公开，并且没有前导下划线。

我在文件开头声明了__all__，并附有我的公共函数名称列表。

当尝试使用epydoc 为该模块生成文档时，epydoc 将模块中的所有内容 视为私有。而且，由于我使用的是--no-private 标志，这意味着输出只显示模块本身的文档，而不是模块的元素或它们各自的文档。

如果我不将 --no-private 标志与 epydoc 一起使用，则所有内容都会记录在案。但我不想要那里的私人事物。关键是：如果我注释掉我的 __all__，epydoc 只会正确记录我模块的公共元素。

我是一个相对的 Python 新手，但据我了解，__all__ 旨在让您在导入其他模块然后其他模块导入您的模块时避免麻烦，并试图对事情保持更严格的限制当一切都技术上公开时，只要您知道您要访问的内容的名称。省略 __all__ 会导致 Bad Things™，或者我被告知。同时，epydoc 左右声称它尊重__all__ 决定什么是公开的，什么不是。

是我错误地使用了 epydoc，错误地假设了我的代码中 __all__ 的使用，还是 epydoc 中的错误？ （我已经解决了 epydoc 中的一个错误处理错误，这显然是由较新版本的 docutils 引起的。）

Answer 1

当使用 epydoc 记录多个文件时，此问题会消失。这似乎是 epydoc 中的一个错误，但它很容易解决，只要您有一个实际的包来记录，而不是单个模块。