sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

autodoc: documenting aliases

Open LecrisUT opened this issue 3 months ago • 0 comments

Describe the bug

With the recent support for PEP695, the documentation of module level aliases does not have the docstrings inherited, unlike non-type members, i.e. if we have a structure like

# Top-level package
from .utils import Lattice

__all__ = ["Lattice"]
# Actual implementation (under `.utils`)
type Lattice = Sequence[Sequence[float]]

__all__ = ["Lattice"]

The documentation is different in the top-level Image compared to the actual implementation Image


There is a greater question here though, should the top-level re-implement the documentation, or have a different type and completely link itself to the real implementation (would prefer the latter personally). Whether or not we would want the aliases to be documented could also be configurable, but we would want to at least be able to document them in one form or another particularly if they are explicitly listed in the __all__

How to Reproduce

See snippet above

Environment Information

sphinx master branch after PEP 695 support.

Sphinx extensions


Additional context

Split from https://github.com/sphinx-doc/sphinx/issues/11561#issuecomment-3543816778

LecrisUT avatar Nov 25 '25 13:11 LecrisUT