Render Python properties with the property directive

Fixes #352.

CHANGELOG.rst

@@ -3,9 +3,21 @@ Changelog
 
 Versions follow `Semantic Versioning <https://semver.org/>`_ (``<major>.<minor>.<patch>``).
 
-v1.9.1 (TBC)
+v2.0.0 (TBC)
 ------------
 
+Breaking Changes
+^^^^^^^^^^^^^^^^
+
+* Dropped support for Sphinx <4.
+* `#352 <https://github.com/readthedocs/sphinx-autoapi/issues/352>`: (Python)
+  Properties are rendered with the ``property`` directive,
+  fixing support for Sphinx 5.2.
+  A new ``PythonPythonMapper`` object (``PythonProperty``) has been created
+  to support this change. This object can be passed to templates, filters,
+  and hooks.
+  A new ``property.rst`` template has also been created to support this change.
+
 Trivial/Internal Changes
 ^^^^^^^^^^^^^^^^^^^^^^^^
 * Use https links where possible in documentation.

autoapi/documenters.py

@@ -6,6 +6,7 @@
     PythonFunction,
     PythonClass,
     PythonMethod,
+    PythonProperty,
     PythonData,
     PythonAttribute,
     PythonException,
@@ -192,8 +193,11 @@ def import_object(self):
 
         if result:
             self.parent = self._method_parent
-            if self.object.method_type != "method":
-                # document class and static members before ordinary ones
+            if "staticmethod" in self.object.properties:
+                # document static members before ordinary ones
+                self.member_order = self.member_order - 2
+            elif "classmethod" in self.object.properties:
+                # document class members before ordinary ones but after static ones
                 self.member_order = self.member_order - 1
 
         return result
@@ -212,22 +216,28 @@ def add_directive_header(self, sig):
                 self.add_line("   :{}:".format(property_type), sourcename)
 
 
-class AutoapiPropertyDocumenter(
-    AutoapiMethodDocumenter, AutoapiDocumenter, autodoc.PropertyDocumenter
-):
+class AutoapiPropertyDocumenter(AutoapiDocumenter, autodoc.PropertyDocumenter):
     objtype = "apiproperty"
-    directivetype = "method"
-    # Always prefer AutoapiDocumenters
-    priority = autodoc.MethodDocumenter.priority * 100 + 100 + 1
+    directivetype = "property"
+    priority = autodoc.PropertyDocumenter.priority * 100 + 100
 
     @classmethod
     def can_document_member(cls, member, membername, isattr, parent):
-        return isinstance(member, PythonMethod) and "property" in member.properties
+        return isinstance(member, PythonProperty)
 
     def add_directive_header(self, sig):
-        super(AutoapiPropertyDocumenter, self).add_directive_header(sig)
+        autodoc.ClassLevelDocumenter.add_directive_header(self, sig)
+
         sourcename = self.get_sourcename()
-        self.add_line("   :property:", sourcename)
+        if self.options.annotation and self.options.annotation is not autodoc.SUPPRESS:
+            self.add_line("   :type: %s" % self.options.annotation, sourcename)
+
+        for property_type in (
+            "abstractmethod",
+            "classmethod",
+        ):
+            if property_type in self.object.properties:
+                self.add_line("   :{}:".format(property_type), sourcename)
 
 
 class AutoapiDataDocumenter(AutoapiDocumenter, autodoc.DataDocumenter):

autoapi/mappers/python/__init__.py

@@ -5,6 +5,7 @@
     PythonModule,
     PythonMethod,
     PythonPackage,
+    PythonProperty,
     PythonAttribute,
     PythonData,
     PythonException,

autoapi/mappers/python/mapper.py

@@ -19,6 +19,7 @@
     PythonModule,
     PythonMethod,
     PythonPackage,
+    PythonProperty,
     PythonAttribute,
     PythonData,
     PythonException,
@@ -237,12 +238,12 @@ class PythonSphinxMapper(SphinxMapperBase):
             PythonModule,
             PythonMethod,
             PythonPackage,
+            PythonProperty,
             PythonAttribute,
             PythonData,
             PythonException,
         )
     }
-    _OBJ_MAP["property"] = PythonMethod
 
     def __init__(self, app, template_dir=None, url_root=None):
         super(PythonSphinxMapper, self).__init__(app, template_dir, url_root)
@@ -421,7 +422,7 @@ def _record_typehints(self, obj):
         if (
             isinstance(obj, (PythonClass, PythonFunction, PythonMethod))
             and not obj.overloads
-        ):
+        ) or isinstance(obj, PythonProperty):
             obj_annotations = {}
 
             include_return_annotation = True

autoapi/mappers/python/objects.py

@@ -169,7 +169,7 @@ class PythonFunction(PythonPythonMapper):
 
     type = "function"
     is_callable = True
-    member_order = 40
+    member_order = 30
 
     def __init__(self, obj, **kwargs):
         super(PythonFunction, self).__init__(obj, **kwargs)
@@ -219,13 +219,6 @@ class PythonMethod(PythonFunction):
     def __init__(self, obj, **kwargs):
         super(PythonMethod, self).__init__(obj, **kwargs)
 
-        self.method_type = obj.get("method_type")
-        """The type of method that this object represents.
-
-        This can be one of: method, staticmethod, or classmethod.
-
-        :type: str
-        """
         self.properties = obj["properties"]
         """The properties that describe what type of method this is.
 
@@ -242,11 +235,34 @@ def _should_skip(self):  # type: () -> bool
         return self._ask_ignore(skip)
 
 
+class PythonProperty(PythonPythonMapper):
+    """The representation of a property on a class."""
+
+    type = "property"
+    member_order = 60
+
+    def __init__(self, obj, **kwargs):
+        super(PythonProperty, self).__init__(obj, **kwargs)
+
+        self.annotation = obj["return_annotation"]
+        """The type annotation of this property.
+
+        :type: str or None
+        """
+        self.properties = obj["properties"]
+        """The properties that describe what type of property this is.
+
+        Can be any of: abstractmethod, classmethod
+
+        :type: list(str)
+        """
+
+
 class PythonData(PythonPythonMapper):
     """Global, module level data."""
 
     type = "data"
-    member_order = 10
+    member_order = 40
 
     def __init__(self, obj, **kwargs):
         super(PythonData, self).__init__(obj, **kwargs)
@@ -272,7 +288,7 @@ class PythonAttribute(PythonData):
     """An object/class level attribute."""
 
     type = "attribute"
-    member_order = 10
+    member_order = 60
 
 
 class TopLevelPythonPythonMapper(PythonPythonMapper):
@@ -335,7 +351,7 @@ class PythonClass(PythonPythonMapper):
     """The representation of a class."""
 
     type = "class"
-    member_order = 30
+    member_order = 20
 
     def __init__(self, obj, **kwargs):
         super(PythonClass, self).__init__(obj, **kwargs)
@@ -409,6 +425,10 @@ def docstring(self, value):
     def methods(self):
         return self._children_of_type("method")
 
+    @property
+    def properties(self):
+        return self._children_of_type("property")
+
     @property
     def attributes(self):
         return self._children_of_type("attribute")
@@ -446,4 +466,4 @@ class PythonException(PythonClass):
     """The representation of an exception class."""
 
     type = "exception"
-    member_order = 20
+    member_order = 10

autoapi/mappers/python/parser.py

@@ -150,18 +150,23 @@ def parse_functiondef(self, node):  # pylint: disable=too-many-branches
 
         if node.type == "function":
             type_ = "function"
+
+            if isinstance(node, astroid.AsyncFunctionDef):
+                properties.append("async")
         elif astroid_utils.is_decorated_with_property(node):
             type_ = "property"
-            properties.append("property")
+            if node.type == "classmethod":
+                properties.append(node.type)
+            if node.is_abstract(pass_is_abstract=False):
+                properties.append("abstractmethod")
         else:
             # "__new__" method is implicit classmethod
             if node.type in ("staticmethod", "classmethod") and node.name != "__new__":
                 properties.append(node.type)
             if node.is_abstract(pass_is_abstract=False):
                 properties.append("abstractmethod")
-
-        if isinstance(node, astroid.AsyncFunctionDef):
-            properties.append("async")
+            if isinstance(node, astroid.AsyncFunctionDef):
+                properties.append("async")
 
         data = {
             "type": type_,
@@ -177,9 +182,6 @@ def parse_functiondef(self, node):  # pylint: disable=too-many-branches
             "overloads": [],
         }
 
-        if type_ in ("method", "property"):
-            data["method_type"] = node.type
-
         result = [data]
 
         if node.name == "__init__":

autoapi/templates/python/class.rst

@@ -32,6 +32,14 @@
    {{ klass.render()|indent(3) }}
    {% endfor %}
    {% if "inherited-members" in autoapi_options %}
+   {% set visible_properties = obj.properties|selectattr("display")|list %}
+   {% else %}
+   {% set visible_properties = obj.properties|rejectattr("inherited")|selectattr("display")|list %}
+   {% endif %}
+   {% for property in visible_properties %}
+   {{ property.render()|indent(3) }}
+   {% endfor %}
+   {% if "inherited-members" in autoapi_options %}
    {% set visible_attributes = obj.attributes|selectattr("display")|list %}
    {% else %}
    {% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}

autoapi/templates/python/function.rst

@@ -5,14 +5,11 @@
               {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
 
 {% endfor %}
-   {% if sphinx_version >= (2, 1) %}
    {% for property in obj.properties %}
    :{{ property }}:
    {% endfor %}
-   {% endif %}
 
    {% if obj.docstring %}
    {{ obj.docstring|indent(3) }}
-   {% else %}
    {% endif %}
 {% endif %}

autoapi/templates/python/method.rst

@@ -1,5 +1,4 @@
 {%- if obj.display %}
-{% if sphinx_version >= (2, 1) %}
 .. py:method:: {{ obj.short_name }}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
 
 {% for (args, return_annotation) in obj.overloads %}
@@ -14,13 +13,6 @@
    {% else %}
 
    {% endif %}
-{% else %}
-.. py:{{ obj.method_type }}:: {{ obj.short_name }}({{ obj.args }})
-{% for (args, return_annotation) in obj.overloads %}
-   {{ " " * (obj.method_type | length) }}   {{ obj.short_name }}({{ args }})
-{% endfor %}
-
-{% endif %}
    {% if obj.docstring %}
    {{ obj.docstring|indent(3) }}
    {% endif %}

autoapi/templates/python/property.rst

@@ -0,0 +1,15 @@
+{%- if obj.display %}
+.. py:property:: {{ obj.short_name }}
+   {% if obj.annotation %}
+   :type: {{ obj.annotation }}
+   {% endif %}
+   {% if obj.properties %}
+   {% for property in obj.properties %}
+   :{{ property }}:
+   {% endfor %}
+   {% endif %}
+
+   {% if obj.docstring %}
+   {{ obj.docstring|indent(3) }}
+   {% endif %}
+{% endif %}

docs/reference/templates.rst

@@ -73,6 +73,10 @@ Python
 	:members:
 	:show-inheritance:
 
+.. autoapiclass:: autoapi.mappers.python.objects.PythonProperty
+	:members:
+	:show-inheritance:
+
 .. autoapiclass:: autoapi.mappers.python.objects.PythonData
 	:members:
 	:show-inheritance:

setup.cfg

@@ -36,7 +36,7 @@ install_requires =
     astroid>=2.7
     Jinja2
     PyYAML
-    sphinx>=3.0
+    sphinx>=4.0
     unidecode
 
 [options.extras_require]