search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.45k stars 2.1k forks source link

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

Open felixblanke opened 3 months ago

felixblanke commented 3 months ago

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). ```python 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:

electric-coder commented 3 months ago

After thinking about it this might actually be a bug. There's a default text for common Python constructs like the __dunder__ magic methods that gets inserted automatically when a member is being documented that doesn't have a docstring.

So I'd say there should not be a configuration option for this because of 2 reasons:

  1. There's no specific configuration for the other default documentation strings that get inserted.
  2. autodoc+napoleon+sphinx already have dozens of configuration options and adding more for a type-specific nicety doesn't justify the added complexity IMO.

I do think that the right choice is omitting the default message if the type alias has its own docstring, that's what currently happens for other common constructs.

felixblanke commented 3 months ago

I agree, that would be preferable. From the past issues on this topic I had the impression that the general behavior of always adding the line is intended and only corner cases were fixed (that's the reason why I proposed this as an optional change). However, that was probably wrong and this should indeed rather be a bug report for the autodata and autoattribute directives than a feature request.

For example, the following case using the autoclass directive is contained in the unit tests:

Alias = Foo

#: docstring
OtherAlias = Bar

yielding 

.. py:attribute:: Alias
   :module: target.classes

   alias of :py:class:`~target.classes.Foo`

.. py:attribute:: OtherAlias
   :module: target.classes

   docstring