Thank you for proposal. Seems good to me. But, sadly, we have a plan to separate property to an independent directive (see #7068) in 3.1.0. So I'd not like to merge this into 3.0.

What are your thoughts on the part of this patch which allows:

.. attr:: MyClass.attr : int
    docs

for consistency with

.. method:: MyClass.meth() -> int
    docs

I could put that part in separately.

Since 2.4.0, we've provided :type: option to describe the type of an attribute:

.. attr:: MyClass.attr
   :type: int

    docs

So that is already implemented in different way.

I'm aware it's already possible to provide this data to sphinx.

My suggestion is more about matching python syntax. Due to python 3.5 supporting:

def meth() -> int:
    pass

you added support for writing

.. method:: meth() -> int

as a short version of

.. method:: meth()
    :rtype: int

Python 3.6+ now supports:

some_var : int

So by symmetry, I think it makes sense to support

.. data:: some_var : int

as a short version of

.. data:: some_var 
    :type: int

Okay, I understand.

Before starting the discussion, I need to correct your misunderstanding. :rtype: is not a short version of -> type. It's a part of content of directive (it's a field-list!), not an option of the directive.

.. py:function:: hello(name)

   blah blah blah

   :param name: the name of user who logs in
   :type name: str
   :rtype: str

It was added before type annotations support in python. So it does not modify the signature of function in the generated document. Surely they are similar, but different notation.

On the other hand, :type: is an option of the directive to annotate the data members and attributes. So it will be conflicted with the : type annotation if adopted. So I think :type: option would be deprecated if we adopted a new style.

The reason why I added :type: option instead of : type notation is the existence of its value. So far, we use :annotation: option for a long to describe the value of the data member:

.. py:data:: name
   :annotation: = 'tk0miya'

This declaration will be converted to `name = 'tk0miya'`.

On development 2.4, I separated the :annotation: option to two options; :type: and :value:. At that time, I thought to give python style signature to the argument (ex. .. py:data:: name: str = 'tk0miya') once. But I thought that passing them as directive options is simpler than passing them as a python-like string. To be precise, I hesitate to build and parse a python-like string on two modules. In introspect, the python way is easy to understand for users.

Anyway, 3.0.x branch is now under feature freeze for the coming release. No more breaking changes and deprecations are prohibited. So it would be better to change these ideas on 3.x branch.

Agreed

Okay, I understand.

Before starting the discussion, I need to correct your misunderstanding. :rtype: is not a short version of -> type. It's a part of content of directive (it's a field-list!), not an option of the directive.

.. py:function:: hello(name)

   blah blah blah

   :param name: the name of user who logs in
   :type name: str
   :rtype: str

It was added before type annotations support in python. So it does not modify the signature of function in the generated document. Surely they are similar, but different notation.

On the other hand, :type: is an option of the directive to annotate the data members and attributes. So it will be conflicted with the : type annotation if adopted. So I think :type: option would be deprecated if we adopted a new style.

Thanks for the explanation, that makes sense to me

The reason why I added :type: option instead of : type notation is the existence of its value. So far, we use :annotation: option for a long to describe the value of the data member:

.. py:data:: name
   :annotation: = 'tk0miya'

This declaration will be converted to `name = 'tk0miya'`.

On development 2.4, I separated the :annotation: option to two options; :type: and :value:. At that time, I thought to give python style signature to the argument (ex. .. py:data:: name: str = 'tk0miya') once.

I think what I actually care about most is that when viewing the web docs, I'd prefer to see the documentation in the form

name : str = 'tk0miya'

instead of

name = 'tk0miya'
    type: str

I suppose this is orthogonal though, and there's no need to make the rst match.

But I thought that passing them as directive options is simpler than passing them as a python-like string. To be precise, I hesitate to build and parse a python-like string on two modules. In introspect, the python way is easy to understand for users.

I'd argue it's (slightly) confusing to the user that they can write their method docs using python syntax, but have to fall back to directive options to build method docs.

Perhaps the hesistation would go away if ast.parse were used to parse the python string instead of regex?

I think what I actually care about most is that when viewing the web docs, I'd prefer to see the documentation in the form

As you said, this is not related to the notations. In fact, the current python domain generates such output.

.. py:data:: name
   :type: str
   :value: 'tk0miya'

I'd argue it's (slightly) confusing to the user that they can write their method docs using python syntax, but have to fall back to directive options to build method docs.

What do you mean? I guess nobody confuses by method notation. And there no directive options to describe the type of method.

Perhaps the hesistation would go away if ast.parse were used to parse the python string instead of regex?

Yes, acceptable.

Thank you for proposal. Seems good to me. But, sadly, we have a plan to separate property to an independent directive (see #7068) in 3.1.0. So I'd not like to merge this into 3.0.

What is the status of this plan? All the referenced PRs appear to be closed without merging.

I think what I actually care about most is that when viewing the web docs, I'd prefer to see the documentation in the form

As you said, this is not related to the notations. In fact, the current python domain generates such output.

.. py:data:: name
   :type: str
   :value: 'tk0miya'

Is this limited to data? I can't seem to get it to work for attr.

Ping, @tk0miya - could you respond to the above comment?

What is the status of this plan? All the referenced PRs appear to be closed without merging.

Now I reopened #7298. I'll work for it in this week. Please wait for a moment.

Is this limited to data? I can't seem to get it to work for attr.

Really? It seems working fine on my local:

.. py:attribute:: foo
   :type: str
   :value: 'tk0miya'

Really? It seems working fine on my local

Yep, works fine for me too now - I can only assume the CI i was using had a different sphinx version to what I thought. Sorry for wasting your time!