Merge pull request #197 from WilliamJamieson/autoproperty

Add option to document properties using autoproperty instead of autoattribute

Author: astrofrog

CHANGES.rst

@@ -4,6 +4,10 @@ Changes in sphinx-automodapi
 0.19.0 (unreleased)
 -------------------
 
+- Add ``automodsumm_properties_are_attributes`` configuration to control if
+  class properties are treated with ``autoattribute`` or ``autoproperty``.
+  [#197]
+
 0.18.0 (2024-09-13)
 -------------------
 

sphinx_automodapi/automodapi.py

@@ -104,6 +104,11 @@ class are included in the generated documentation. Defaults to ``False``.
     methods like ``__getitem__`` and ``__setitem__``. Defaults to
     ``['__init__', '__call__']``.
 
+* ``automodsumm_properties_are_attributes``
+    Should be a bool and if ``True`` properties are treated as attributes in the
+    documentation meaning that no property specific documentation is generated.
+    Defaults to ``True``.
+
 .. _automodule: http://sphinx-doc.org/latest/ext/autodoc.html?highlight=automodule#directive-automodule
 """
 

sphinx_automodapi/automodsumm.py

@@ -74,6 +74,11 @@ class members that are inherited from a base class. This value can be
     methods like ``__getitem__`` and ``__setitem__``. Defaults to
     ``['__init__', '__call__']``.
 
+* ``automodsumm_properties_are_attributes``
+    Should be a bool and if ``True`` properties are treated as attributes in the
+    documentation meaning that no property specific documentation is generated.
+    Defaults to ``True``.
+
 .. _sphinx.ext.autosummary: http://sphinx-doc.org/latest/ext/autosummary.html
 .. _autosummary: http://sphinx-doc.org/latest/ext/autosummary.html#directive-autosummary
 
@@ -321,7 +326,8 @@ def process_automodsumm_generation(app):
                 lines, sfn, app=app, builder=app.builder,
                 base_path=app.srcdir,
                 inherited_members=app.config.automodsumm_inherited_members,
-                included_members=app.config.automodsumm_included_members)
+                included_members=app.config.automodsumm_included_members,
+                properties_are_attributes=app.config.automodsumm_properties_are_attributes)
 
 
 # _automodsummrex = re.compile(r'^(\s*)\.\. automodsumm::\s*([A-Za-z0-9_.]+)\s*'
@@ -462,7 +468,8 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst',
                               base_path=None, builder=None,
                               template_dir=None,
                               inherited_members=False,
-                              included_members=('__init__', '__call__')):
+                              included_members=('__init__', '__call__'),
+                              *, properties_are_attributes=True):
     """
     This function is adapted from
     `sphinx.ext.autosummary.generate.generate_autosummmary_docs` to
@@ -595,10 +602,10 @@ def get_members_class(obj, typ, include_public=[],
                         continue
                     if typ is None or documenter.objtype == typ:
                         items.append(name)
-                    elif typ == 'attribute' and documenter.objtype == 'property':
-                        # In Sphinx 2.0 and above, properties have a separate
-                        # objtype, but we treat them the same here.
-                        items.append(name)
+                    # elif typ == 'attribute' and documenter.objtype == 'property':
+                    #     # In Sphinx 2.0 and above, properties have a separate
+                    #     # objtype, but we treat them the same here.
+                    #     items.append(name)
                 public = [x for x in items
                           if x in include_public or not x.startswith('_')]
                 return public, items
@@ -629,6 +636,15 @@ def get_members_class(obj, typ, include_public=[],
                 ns['attributes'], ns['all_attributes'] = \
                     get_members_class(obj, 'attribute',
                                       include_base=include_base)
+                public_properties, all_properties = \
+                    get_members_class(obj, 'property',
+                                      include_base=include_base)
+                if properties_are_attributes:
+                    ns['attributes'].extend(public_properties)
+                    ns['all_attributes'].extend(all_properties)
+                else:
+                    ns['properties'] = public_properties
+                    ns['all_properties'] = all_properties
                 ns['methods'].sort()
                 ns['attributes'].sort()
 
@@ -703,6 +719,7 @@ def setup(app):
     app.add_config_value('automodsumm_inherited_members', False, 'env')
     app.add_config_value(
         'automodsumm_included_members', ['__init__', '__call__'], 'env')
+    app.add_config_value('automodsumm_properties_are_attributes', True, 'env')
 
     return {'parallel_read_safe': True,
             'parallel_write_safe': True}

sphinx_automodapi/templates/autosummary_core/class.rst

@@ -18,7 +18,7 @@
    {% endif %}
 
    {% block attributes_summary %}
-   {% if attributes %}
+   {% if attributes or properties %}
 
    .. rubric:: Attributes Summary
 
@@ -27,6 +27,10 @@
       ~{{ name }}.{{ item }}
    {%- endfor %}
 
+   {% for item in properties %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
    {% endif %}
    {% endblock %}
 
@@ -44,14 +48,18 @@
    {% endblock %}
 
    {% block attributes_documentation %}
-   {% if attributes %}
+   {% if attributes or properties%}
 
    .. rubric:: Attributes Documentation
 
    {% for item in attributes %}
    .. autoattribute:: {{ item }}
    {%- endfor %}
 
+   {% for item in properties %}
+   .. autoproperty:: {{ item }}
+   {%- endfor %}
+
    {% endif %}
    {% endblock %}
 

sphinx_automodapi/tests/cases/abstract_classes/output/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst renamed to sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/api/sphinx_automodapi.tests.example_module.abstract_classes.SequenceSubclass.rst

@@ -0,0 +1,27 @@
+SequenceSubclass
+================
+
+.. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes
+
+.. autoclass:: SequenceSubclass
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+
+      ~SequenceSubclass.my_property
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~SequenceSubclass.my_method
+
+   .. rubric:: Attributes Documentation
+
+   .. autoproperty:: my_property
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: my_method

sphinx_automodapi/tests/cases/abstract_classes/output/index.rst.automodapi renamed to sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodapi

@@ -0,0 +1,19 @@
+
+sphinx_automodapi.tests.example_module.abstract_classes Module
+--------------------------------------------------------------
+
+.. automodule:: sphinx_automodapi.tests.example_module.abstract_classes
+
+Classes
+^^^^^^^
+
+.. automodsumm:: sphinx_automodapi.tests.example_module.abstract_classes
+    :classes-only:
+    :toctree: api
+
+Class Inheritance Diagram
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automod-diagram:: sphinx_automodapi.tests.example_module.abstract_classes
+    :private-bases:
+    :parts: 1

sphinx_automodapi/tests/cases/abstract_classes/output/index.rst.automodsumm renamed to sphinx_automodapi/tests/cases/abstract_classes/output_prop_is_attr/index.rst.automodsumm

@@ -0,0 +1,6 @@
+.. currentmodule:: sphinx_automodapi.tests.example_module.abstract_classes
+
+.. autosummary::
+    :toctree: api
+
+    SequenceSubclass