I have a module containing multiple global functions, and a global variable. The variable and some of the functions follow the ‘private’ naming convention for Python, with a leading underscore for the name. The other functions are intended to be public, and do not have a leading underscore.
I have declared __all__, with a list of my public function names, at the beginning of my file.
When trying to generate documentation for this module using epydoc, epydoc is considering everything in the module as private. And, since I’m using the --no-private flag, this means that the output only shows the documentation on the module itself, not the elements of the module or their individual documentation.
If I don’t use the --no-private flag with epydoc, everything gets documented. But I don’t want the private things there. Here’s the kicker: If I comment out my __all__, epydoc correctly documents only the public elements of my module.
I’m a relative Python newbie, but as I understand it, __all__ is meant to keep you out of trouble when you import other modules and then other modules import yours, and for trying to keep a tighter lid on things when everything is technically public, so long as you know the name of what you’re trying to access. Omitting __all__ can lead to Bad Things™, or so I’m told. At the same time, epydoc claims right and left that it honors __all__ for deciding what is public and what isn’t.
Is it that I’m using epydoc wrong, assuming incorrectly about the usage of __all__ in my code, or a bug in epydoc? (I’ve already resolved one error handling bug in epydoc which is apparently caused by newer versions of docutils.)
This problem disappears when using epydoc to document more than one file. It seems to be a bug in epydoc, but it’s easily worked around, so long as you have an actual package to document, rather than a single module.