python - 使用 epydoc 记录公共(public)全局函数

Question

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

我已声明__all__ ，在文件的开头列出了我的公共(public)函数名称。

尝试使用epydoc为此模块生成文档时，epydoc 正在将模块中的所有内容视为私有(private)。而且，因为我正在使用 --no-private标志，这意味着输出仅显示模块本身的文档，而不显示模块的元素或其单独的文档。

如果我不使用--no-private用 epydoc 标记，一切都会被记录下来。但我不想要那里的私有(private)东西。关键在于:如果我注释掉我的 __all__ ，epydoc 仅正确记录我模块的公共(public)元素。

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

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

Answer 1

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