Autodoc feature request: Attribute docstring signatures

[drewcassidy]

Is your feature request related to a problem? Please describe.
Right now theres no way for a docstring for an attribute to define its type option, only a type field, which is frustrating when documenting extension modules. I propose the autodoc_docstring_signature feature be extended to include attributes to allow type documentation from within non-python code.

Currently the only workarounds I'm aware of are

• manually document each attribute
• use the function signature syntax (e.g. .. autoproperty:: field(type)) which is kinda weird
• to use the :type: field which makes the documentation a lot messier looking than I would like

Describe the solution you'd like
similar to functions, allow for the first line of an attribute docstring to contain a signature in the form name: type, and have that type automatically added to the :type: option (not field) of the auto documented member.

Describe alternatives you've considered

• removing the newline from before :type: fields on the first line of a docstring to make them into options instead
• using a function style signature (e.g. name(self)-> type) (this is probably the easiest to implement by reusing the method signature function)

Additional context

• this is a similar problem to napoleon: docstrings do not produce type annotations #7582 but not with napoleon

I'm open to doing a PR for this feature, I just want feedback on what the best way to go about doing it is, and if anyone else wants it.

[brenthuisman]

Possibly related:

I have a Pybind project with a class with a property with the following docstring: ":type: int\n\nThe id of the branch.". This generates something like the first example in your image, but I'd like the second.

"the_prop() -> int\n\nThe id of the branch." seems to be picked up, because it disappears from the output, but it's not used to add in the type of the property at all.

When I create some documentation without autodoc, I see that a newline matters. To generate what I see in your example:

.. class:: someclass

    .. attribute:: two_ls_passes

        :type: bool

    .. attribute:: two_ls_passes
        :type: bool

I'm wondering if autodoc adds this newline as well, and if I can remove it somehow.

[shimizukawa]

If sphinx supports pyi files, it would be better than using docstrings to specify types.
i.e. #7630

[drewcassidy]

Im not thrilled with the idea of using pyi files if only because it means juggling even more files for an extension module

[tk0miya]

I agree with @shimizukawa's idea. The .pyi file is now the standard of Python to distribute type information (see PEP 561; https://www.python.org/dev/peps/pep-0561/). It also helps type checkers, IDEs, and other typing tools. There is no reason to add an original docstring format only for documentation to me.

[drewcassidy]

Is there any further documentation on pyi files? I have no idea where to put them or how to write them

[drewcassidy]

never mind, i think I figured it out. I agree that this is the best way to go

[tk0miya]

Thank you for your understanding.
We must hurry to implement .pyi file support!