Proposal: Document each member at the lowest-level submodule, with higher level modules pointing at submodule's primary declaration without duplicating them.

Problem Description

I want to be able to import classes and functions to higher level modules, for developer convenience, but without insane redundancies in where classes are defined.

In other words, I want to reduce reader fatigue by giving the authoritative reference for any class or function in a single location - while other reference point to those references.

Proposal

Whenever a class is import from a submodule to a parent module, the parent module will "point to" the lower level module, without redundantly documenting it.

Alternatives

I'm not aware of any alternative - although perhaps someone has something very clever in custom rendering templates...

Additional context

Take SQLAlchemy Engine - it can be imported as from sqlalchemy import Engine or from sqlalchemy.engine import Engine. One can make a case that classes which are used extremely often should be easily importable at higher levels in the module hierarchy.

However, with pdoc today, there isn't a way (that I'm aware of at least) to have an index of members at the level they are imported, while still reserving the deep and full documentation of those members for the submodules where they are declared.

One final layer of context is that with modern Python applications, SDKs, and libraries, typing is increasingly a mandatory and required practice. It is not longer sufficient to simply know which functions or classes we are directly calling; we also need to know how to type the classes that are being passed and returned to/from those interfaces. Hence, convenience must be balanced with practicality and intuitive module design - and it is increasingly unlikely that each package member will be declared exactly once in any library. Rather than put full documentation at every node in the hierarchy, it would be a better end-user experience to have a single 'authoritative' location for each member, at the lowest level, with other convenience imports pointing at that member rather than redundantly describing it.

Implementation Option

To implement, a check could be added: if a member that would be documented in a parent module will also be rendered in one of its submodules, then rather than document the entire member, simply declare it and link to the submodule's reference.

This logic can be repeated recursively, down to the lowest-level declared and documented submodule (excluding private or un-rendered submodules).

The issue does not name implementation files, tests, or entry points. Start by tracing how imported members are currently rendered at parent and submodule levels, then define the recursive linking behavior and tests needed to confirm that each member has one authoritative rendered location.