diff --git a/{{cookiecutter.project_name}}/docs/_templates/autosummary/class.rst b/{{cookiecutter.project_name}}/docs/_templates/autosummary/class.rst index 7b4a0cf8..7252c8c8 100644 --- a/{{cookiecutter.project_name}}/docs/_templates/autosummary/class.rst +++ b/{{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 %} diff --git a/{{cookiecutter.project_name}}/docs/_templates/autosummary/module.rst b/{{cookiecutter.project_name}}/docs/_templates/autosummary/module.rst new file mode 100644 index 00000000..9c0b618d --- /dev/null +++ b/{{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 %} diff --git a/{{cookiecutter.project_name}}/docs/extensions/member_type.py b/{{cookiecutter.project_name}}/docs/extensions/member_type.py new file mode 100644 index 00000000..d3e061cb --- /dev/null +++ b/{{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