-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Make addition of "alias of..." text optional #12484
Comments
After thinking about it this might actually be a bug. There's a default text for common Python constructs like the So I'd say there should not be a configuration option for this because of 2 reasons:
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. |
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 For example, the following case using the 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 |
…ng present autodoc: Do not add an 'alias of ...' line using the `autodata` and `autoattribute` directives for generic aliases having docstrings.
autodoc: Do not add an 'alias of ...' line using the `autodata` and `autoattribute` directives for generic aliases having docstrings.
autodoc: Do not add an 'alias of ...' line using the `autodata` and `autoattribute` directives for generic aliases having docstrings.
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).
If I then use autodoc to document the type aliases:
The result is
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 writeto 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 inconf.py
(similar toautodoc_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:
The text was updated successfully, but these errors were encountered: