Docs fixes / improvements

{{cookiecutter.project_name}}/docs/_templates/autosummary/class.rst

@@ -1,61 +1,54 @@
-{{ fullname | escape | underline}}
+{{ fullname | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
 .. add toctree option to make autodoc generate the pages
 
-.. autoclass:: {{ objname }}
+.. autoclass:: {{ fullname }}
 
-{% block attributes %}
-{% if attributes %}
-Attributes table
-~~~~~~~~~~~~~~~~
+{% set methods = methods | select("ne", "__init__") | list %}
 
-.. autosummary::
+{% block attributes %}
 {% for item in attributes %}
-    ~{{ name }}.{{ item }}
-{%- endfor %}
+{% if loop.first %}
+    Attributes table
+    ~~~~~~~~~~~~~~~~
+
+    .. autosummary::
 {% endif %}
+        ~{{ name }}.{{ item }}
+{%- endfor %}
 {% endblock %}
 
 {% block methods %}
-{% if methods %}
-Methods table
-~~~~~~~~~~~~~
-
-.. autosummary::
 {% for item in methods %}
-    {%- if item != '__init__' %}
-    ~{{ name }}.{{ item }}
-    {%- endif -%}
-{%- endfor %}
+{% if loop.first %}
+    Methods table
+    ~~~~~~~~~~~~~
+
+    .. autosummary::
 {% endif %}
+        ~{{ name }}.{{ item }}
+{% endfor %}
 {% endblock %}
 
 {% block attributes_documentation %}
-{% if attributes %}
-Attributes
-~~~~~~~~~~
-
 {% for item in attributes %}
-
-.. autoattribute:: {{ [objname, item] | join(".") }}
-{%- endfor %}
+{% if loop.first %}
+    Attributes
+    ~~~~~~~~~~
 
 {% endif %}
+    .. auto{{ [fullname, item] | join(".") | member_type }}:: {{ [fullname, item] | join(".") }}
+{%- endfor %}
 {% endblock %}
 
 {% block methods_documentation %}
-{% if methods %}
-Methods
-~~~~~~~
-
 {% for item in methods %}
-{%- if item != '__init__' %}
-
-.. automethod:: {{ [objname, item] | join(".") }}
-{%- endif -%}
-{%- endfor %}
-
+{% if loop.first %}
+    Methods
+    ~~~~~~~
 {% endif %}
+    .. automethod:: {{ [fullname, item] | join(".") }}
+{%- endfor %}
 {% endblock %}

{{cookiecutter.project_name}}/docs/_templates/autosummary/module.rst

@@ -0,0 +1,62 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+    {% block attributes %}
+    {% if attributes %}
+    .. rubric:: {{ _('Module Attributes') }}
+
+    .. autosummary::
+    {% for item in attributes %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block functions %}
+    {% if functions %}
+    .. rubric:: {{ _('Functions') }}
+
+    .. autosummary::
+        :toctree:
+    {% for item in functions %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block classes %}
+    {% if classes %}
+    .. rubric:: {{ _('Classes') }}
+
+    .. autosummary::
+        :toctree:
+    {% for item in classes %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block exceptions %}
+    {% if exceptions %}
+    .. rubric:: {{ _('Exceptions') }}
+
+    .. autosummary::
+        :toctree:
+    {% for item in exceptions %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

{{cookiecutter.project_name}}/docs/extensions/member_type.py

@@ -0,0 +1,34 @@
+"""Extension adding a jinja2 filter that determines a class member’s type."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from jinja2.defaults import DEFAULT_FILTERS
+from jinja2.utils import import_string
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+def member_type(obj_path: str) -> Literal["method", "property", "attribute"]:
+    """Determine object member type.
+
+    E.g.: `.. auto{{ '{{' }} fullname | member_type {{ '}}' }}::`
+    """
+    # https://jinja.palletsprojects.com/en/stable/api/#custom-filters
+    cls_path, member_name = obj_path.rsplit(".", 1)
+    cls = import_string(cls_path)
+    member = getattr(cls, member_name, None)
+    match member:
+        case property():
+            return "property"
+        case _ if callable(member):
+            return "method"
+        case _:
+            return "attribute"
+
+
+def setup(app: Sphinx):
+    """App setup hook."""
+    DEFAULT_FILTERS["member_type"] = member_type