Description
Problem
The __init__.py is sometimes used to re-export functions and classes defined within sub-modules, generally for visibility within the library and also with the auto-completion. It would be nice if the documentation showed this as well.
Solution
Ideally, I would like an option that shows explicit imports/re-exports located within __init__.py. Based on other linting conventions, the way this is done is to be explicit with an as even if it is tautological, though may not always be.
# Explicit import and re-export without changing the name
from .foo import Bar as Bar
# Explicit import and re-export with a name change
from .foo import Baz as FooBazAs for the implementation, I like the way Rust documentation shows re-exports in a section dedicated for re-exports. This makes it clear that the class or function is defined elsewhere but has been made available within the current namespace. Here's an example from the popular Clap library:
Alternatives
I tried looking at the options available, but could not identify anything that would provide the functionality I need.
Another alternative would be to have the gen-files script handle this, but the implementation does not appear to be easy.
Extra
The ability to document re-exports I think could be implemented with the following options if there might be a need for that, though I struggle to see the use-case for any of them other than explicit-init.
explicit-init: This would only document explicit re-exports (i.e., ones that use theasnotation) within__init__.pyfiles.explicit-all: This would document explicit re-exports, but within any Python file.implicit-init: This would document all imports (whether they use the explicitasnotation or not), but only within__init__.pyimplicit-all: As withimplicit-init, but for all files.