使用 epydoc 记录公共全局函数

Question

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

我在文件的开头声明了 __all__ 以及我的公共函数名称列表。

当尝试使用 epydoc 生成此模块的文档时，epydoc 正在考虑以下一切该模块为私有。而且，由于我使用 --no-private 标志，这意味着输出仅显示模块本身的文档，而不显示模块的元素或其单独的文档。

如果我不使用 epydoc 的 --no-private 标志，所有内容都会被记录下来。但我不想要那里的私人事物。关键在于：如果我注释掉我的 __all__，epydoc 会正确地仅记录我模块的公共元素。

我是一个相对的 Python 新手，但据我了解， __all__ 的目的是让您在导入其他模块然后其他模块导入您的模块时避免遇到麻烦，并在所有内容技术上都是公开的情况下尝试对事物进行更严格的限制，只要您知道您要访问的内容的名称。省略 __all__ 可能会导致 Bad Things™，至少有人告诉我。与此同时，epydoc 声称它尊重 __all__ 来决定什么是公开的、什么不是公开的。

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

Answer 1

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