The idea for documenting reimported entities from submodules

Hi!

• I have a function my_lib.my_module.my_function
• I do from .my_module import my_function in my_lib/__init__.py
• I want users to access the function as my_lib.my_function

As far as I understand there is no way to tell pdoc to document the function as my_lib.my_function. Although I see from the website that this is an intentional design decision, I would like to share an idea that is:

• simple
• preserves strong correspondence between the source code and its documentation (i.e. pdoc will be able to fully understand the intended reimports and check their correctness)

The idea is to add a single mapping __pdoc_mapping__ in the root __init__.py (my_lib/__init__.py in the example above) with the following content:

__pdoc_mapping__ = {
    # old_name: new_name
    'my_function': 'my_module.my_function'
}

What do you think?

Start with pdoc's documented decision on reimported entities and the example in my_lib/init.py. Evaluate the proposed pdoc_mapping for documenting my_lib.my_function while preserving source correspondence, then define acceptance tests for the mapping and its correctness before implementation.