[autodoc] Allow :annotation: to be used in docstring

[Jackenmen]

Is your feature request related to a problem? Please describe.
Currently if I want to add an attribute (or module constant) and document it with-in a code (let's assume autoclass/automodule is in usage), I can't stop Sphinx from showing the value of it in that same docstring. Instead, I have to manually do this in automodule directive:

 .. automodule:: module_name
     :members:
+    :exclude-members: CONSTANT_NAME
+
+    .. autodata:: CONSTANT_NAME
+        :annotation:

Describe the solution you'd like
I would want to be able to just add :annotation: directly in the docstring.

Describe alternatives you've considered
Other than naming this role differently in docstring, I don't think there's anything else to do if I want to control this from docstring.

Additional context
N/A

[tk0miya]

+1: Reasonable. Please let me know your opinion before implementation. Is there any reason to control :annotation: individually? Could you accept an option to suppress them all on the document instead of this?

[Jackenmen]

Is there any reason to control :annotation: individually?

I think that individual control might not be as needed in class, but I think that it does make sense to be able to control individual appearance of constants in module. I admit that I don't use auto attribute that often, but from my point of view, the most common use case is to just not show the value of the constant for some specific constant while keeping it for the rest. But if someone uses :annotation: to actually make it show different value, then this is even more important since setting same :annotation: some_value for whole document wouldn't make much sense.

IMO controlling individual :annotation: from docstring would be the must for this, and controls for class-wide and module-wide (maybe document-wide too, I don't know) are just things that could be "good to have" rather than really necessary.

[tk0miya]

Ah, sorry. I'd like to ask your opinion about adding a new configuration like autodoc_suppress_values_for_attributes = True instead of :annotation: option support in docstring. I suspect it controls all of attributes in the Sphinx project. I'm a bit hesitating to add a new metadata to docstring yet. So it might be better to add a new configuration if it satisfies your case.

[Jackenmen]

Oh, I actually thought that such option already exists, but since it would not be useful for me, I didn't check for that in Sphinx's docs.
So yeah, such option wouldn't really be useful for me, as I usually want to show the values of variables/attributes and only sometimes (rather rarely) don't want to show it. I would even say that it's rare enough that I can just do what is shown in the example above, but I like keeping all of this to attribute's docstring rather than changing it in rst file (same as I can for example do with :meta private: since Sphinx 3.0).
IMO a good example of this are enums:

class PermState(enum.Enum):
    NONE = enum.auto()
    """No special privilege level."""
    MOD = enum.auto()
    """User has the mod role."""
    ADMIN = enum.auto()
    """User has the admin role."""
    GUILD_OWNER = enum.auto()
    """User is the guild owner."""
    APP_OWNER = enum.auto()
    """User is an app owner."""


class ConfigCategory(enum.Enum):
    """Represents config category."""

    #: Global category.
    GLOBAL = "GLOBAL"
    #: Guild category.
    GUILD = "GUILD"
    #: Channel category.
    CHANNEL = "TEXTCHANNEL"
    #: Role category.
    ROLE = "ROLE"
    #: User category.
    USER = "USER"
    #: Member category.
    MEMBER = "MEMBER"

While the value of PermState is unimportant (which is why enum.auto() is used), the value of ConfigCategory does have a meaning and showing it in documentation can make sense.

I'm a bit hesitating to add a new metadata to docstring yet. So it might be better to add a new configuration if it satisfies your case.

So in short, it does not satisfy my case, but this is not a critical feature but rather an enhancement, so if you think this shouldn't be added to Sphinx yet, I'll accept that and just keep using the current solution for this with the hope that maybe some day it can be replaced with something that better suits my needs :)

[tk0miya]

Thank you for comment. And I agree with your example PermState. I'll consider what we should do again. Please wait a moment.

[dfremont]

I'd also find this useful: I have some large modules which are auto-documented (using autodoc + napoleon) but have a few attributes whose values are rendered as very long strings. If I were writing my own autodata directives I could use :annotation: to specify an abbreviated form of the value, but I'd much rather have everything automatically generated from the docstrings.