sphinx-doc / sphinx-doc/sphinx

Make addition of "alias of..." text optional

Open
#12,484 2 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.
When autodoc is used to document a type alias, a line is automatically inserted at the end of the handmade docstring containing the string alias of <TYPE>.

I would like to be able to disable this behavior for a type alias to have full control over the shown documentation text. In particular, if the docstring already contains an explanation of the type, the alias of line is redundant.

Further, this would give me more control on how the alias is presented in the documentation. Currently, other type aliases used are always resolved in the alias of line (see #123456), making the line less understandable in complex situations.

Example of such a situation

For example, if I want to document the type alias of a tuple where the first element is a str, followed by an arbitrary amount of objects of another very complex type alias (for the example: pairs of ints).

from typing_extensions import Unpack, TypeAlias

InnerType: TypeAlias = tuple[int, int]
"""Type alias description of the inner type."""

ComplexType: TypeAlias = tuple[str, Unpack[tuple[InnerType, ...]]]
"""Type alias description of the complex type.

Longer description: Type alias of a tuple starting with a str followed by pairs of ints…

"""

If I then use autodoc to document the type aliases:

.. autodata:: ComplexInnerType

.. autodata:: ComplexType

The result is

module-name.InnerType

    Type alias description of the inner type.

    alias of tuple[int, int]

module-name.ComplexType

    Type alias description of the complex type.

    Longer description: Type alias of a tuple starting with a str followed by pairs of ints…

    alias of tuple[str, Unpack[tuple[tuple[int, int], …]]]

Describe the solution you'd like

I would like to add an option per documented object to disable the addition of the alias of... line.
Say, the option is called no-alias. Then, I could write

.. autodata:: ComplexType
    :no-alias:

to disable the addition of the line.

Describe alternatives you've considered

Disabling could also be done by a global option. But this would not give a granular control over the addition of the line.

The removal could also be controlled in conf.py, e.g. by adding an optional set of alias names in conf.py (similar to autodoc_type_aliases) or by adding a hook for the user.
However, I think it's more natural to control this behaviour at the specification of the directive.

Additional context

Possibly related:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the autodoc autodata directive and trace how type aliases receive the generated alias of text and how per-object directive options are handled. Review the related issues and the autodoc_type_aliases configuration mentioned in the report. Done means :no-alias: suppresses the line for that documented object while leaving other aliases unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.