From a142a654fccb4a7c9f5704f55d8aacfe866efd94 Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Tue, 16 Apr 2019 20:31:43 +0900
Subject: [PATCH] Add :property: option to py:method directive

---
 CHANGES                                |  8 ++++++--
 doc/usage/restructuredtext/domains.rst |  6 +++++-
 sphinx/domains/python.py               | 20 ++++++++++++++------
 tests/test_domain_py.py                | 15 ++++++++++++++-
 4 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/CHANGES b/CHANGES
index c337b2087..55e0b5c91 100644
--- a/CHANGES
+++ b/CHANGES
@@ -84,8 +84,12 @@ Features added
   imported members on autosummary
 * #6271: ``make clean`` is catastrophically broken if building into '.'
 * #4777: py domain: Add ``:async:`` option to :rst:dir:`py:function` directive
-* py domain: Add ``:async:``, ``:classmethod:`` and ``:staticmethod:`` options
-  to :rst:dir:`py:method` directive
+* py domain: Add new options to :rst:dir:`py:method` directive
+
+  - ``:async:``
+  - ``:classmethod:``
+  - ``:property:``
+  - ``:staticmethod:``
 
 Bugs fixed
 ----------
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
index 10fbf6f6f..7d616c8c7 100644
--- a/doc/usage/restructuredtext/domains.rst
+++ b/doc/usage/restructuredtext/domains.rst
@@ -229,9 +229,13 @@ The following directives are provided for module and class contents:
    The ``classmethod`` option and ``staticmethod`` option can be given (with
    no value) to indicate the method is a class method (or a static method).
 
+   The ``property`` option can be given (with no value) to indicate the method
+   is a property.
+
    .. versionchanged:: 2.1
 
-      ``:async:``, ``:classmethod:`` and ``:staticmethod:`` options added.
+      ``:async:``, ``:classmethod:``, ``:property:`` and ``:staticmethod:``
+      options added.
 
 .. rst:directive:: .. py:staticmethod:: name(parameters)
 
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index c1ef3f990..c4971ba60 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -587,22 +587,28 @@ class PyMethod(PyObject):
     option_spec.update({
         'async': directives.flag,
         'classmethod': directives.flag,
+        'property': directives.flag,
         'staticmethod': directives.flag,
     })
 
     def needs_arglist(self):
         # type: () -> bool
-        return True
+        if 'property' in self.options:
+            return False
+        else:
+            return True
 
     def get_signature_prefix(self, sig):
         # type: (str) -> str
         prefix = []
         if 'async' in self.options:
             prefix.append('async')
-        if 'staticmethod' in self.options:
-            prefix.append('static')
         if 'classmethod' in self.options:
             prefix.append('classmethod')
+        if 'property' in self.options:
+            prefix.append('property')
+        if 'staticmethod' in self.options:
+            prefix.append('static')
 
         if prefix:
             return ' '.join(prefix) + ' '
@@ -622,10 +628,12 @@ class PyMethod(PyObject):
             else:
                 return '%s()' % name
 
-        if 'staticmethod' in self.options:
-            return _('%s() (%s static method)') % (methname, clsname)
-        elif 'classmethod' in self.options:
+        if 'classmethod' in self.options:
             return _('%s() (%s class method)') % (methname, clsname)
+        elif 'property' in self.options:
+            return _('%s() (%s property)') % (methname, clsname)
+        elif 'staticmethod' in self.options:
+            return _('%s() (%s static method)') % (methname, clsname)
         else:
             return _('%s() (%s method)') % (methname, clsname)
 
diff --git a/tests/test_domain_py.py b/tests/test_domain_py.py
index d3c685388..fac8a838f 100644
--- a/tests/test_domain_py.py
+++ b/tests/test_domain_py.py
@@ -333,7 +333,9 @@ def test_pymethod_options(app):
             "   .. py:method:: meth3\n"
             "      :staticmethod:\n"
             "   .. py:method:: meth4\n"
-            "      :async:\n")
+            "      :async:\n"
+            "   .. py:method:: meth5\n"
+            "      :property:\n")
     domain = app.env.get_domain('py')
     doctree = restructuredtext.parse(app, text)
     assert_node(doctree, (addnodes.index,
@@ -346,6 +348,8 @@ def test_pymethod_options(app):
                                                   addnodes.index,
                                                   desc,
                                                   addnodes.index,
+                                                  desc,
+                                                  addnodes.index,
                                                   desc)])]))
 
     # method
@@ -387,6 +391,15 @@ def test_pymethod_options(app):
     assert 'Class.meth4' in domain.objects
     assert domain.objects['Class.meth4'] == ('index', 'method')
 
+    # :property:
+    assert_node(doctree[1][1][8], addnodes.index,
+                entries=[('single', 'meth5() (Class property)', 'Class.meth5', '', None)])
+    assert_node(doctree[1][1][9], ([desc_signature, ([desc_annotation, "property "],
+                                                     [desc_name, "meth5"])],
+                                   [desc_content, ()]))
+    assert 'Class.meth5' in domain.objects
+    assert domain.objects['Class.meth5'] == ('index', 'method')
+
 
 def test_pyclassmethod(app):
     text = (".. py:class:: Class\n"