Update api template usage (#216)

* docs: Update API template to use the new jinja template format

* docs: Added a section that shows the submodules of each subpackage in the summary

.pre-commit-config.yaml

@@ -49,7 +49,7 @@ repos:
       - id: check-github-workflows
         args: [--verbose]
   - repo: https://github.com/commitizen-tools/commitizen
-    rev: v3.25.0
+    rev: v3.25.1
     hooks:
       - id: commitizen
         stages: [commit-msg]
@@ -64,6 +64,15 @@ repos:
     rev: 1.16.0
     hooks:
       - id: yamlfix
+# TODO: get this working
+#  - repo: https://github.com/motet-a/jinjalint
+#    rev: "0.5"
+#    hooks:
+#      - id: jinjalint
+  - repo: https://github.com/thibaudcolas/curlylint
+    rev: v0.13.1
+    hooks:
+      - id: curlylint
   - repo: https://github.com/executablebooks/mdformat
     rev: 0.7.17
     hooks:

CHANGELOG.md

@@ -18,6 +18,10 @@ Valid subsections within a version are:
 
 Things to be included in the next release go here.
 
+### Added
+
+- Added a new section in the documentation of each package/subpackage that shows the submodules (files) of that package/subpackage.
+
 ### Removed
 
 - docs: Removed the copy code button from the Python API signatures in the documentation.
@@ -26,6 +30,7 @@ Things to be included in the next release go here.
 
 - Updated most `__init__.py` files to not include `__all__` variable definitions.
 - Renamed some of the abstract base classes to separate them from the actual device driver classes.
+- Updated the documentation templates to use the new jinja template style that `mkdocstrings-python` is switching to.
 
 ---
 

docs/_templates/mkdocstrings/python/readthedocs/children.html → docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja

@@ -1,4 +1,15 @@
-{# Original source file: https://github.com/mkdocstrings/python/blob/main/src/mkdocstrings_handlers/python/templates/material/_base/children.html#}
+{# Original source file: https://github.com/mkdocstrings/python/blob/main/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja#}
+{#- Template for members (children) of an object.
+
+This template iterates on members of a given object and renders them.
+It can group members by category (attributes, classes, functions, modules) or render them in a flat list.
+
+Context:
+  obj (griffe.dataclasses.Object): The object to render.
+  config (dict): The configuration options.
+  root_members (bool): Whether the object is the root object.
+  heading_level (int): The HTML heading level to use.
+-#}
 {%- macro create_summary_table(item_list) -%}
     <table>
         <tbody>
@@ -21,7 +32,13 @@
 {%- endmacro -%}
 
 {% if obj.members %}
-  {{ log.debug("Rendering children of " + obj.path) }}
+  {% block logs scoped %}
+    {#- Logging block.
+
+    This block can be used to log debug messages, deprecation messages, warnings, etc.
+    -#}
+    {{ log.debug("Rendering children of " + obj.path) }}
+  {% endblock logs %}
 
   <div class="doc doc-children">
 
@@ -76,6 +93,17 @@
                 {{ create_summary_table(functions) }}
             {% endif %}
         {% endwith %}
+        {% with modules = obj.modules|filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring)|selectattr("is_init_module", "equalto", false)|list|order_members(config.members_order, members_list)
+        %}
+            {% if modules %}
+                {% filter heading(heading_level, id=html_id ~ "-modules") %}Submodules{% endfilter %}
+                {{ create_summary_table(modules) }}
+            {% endif %}
+        {% endwith %}
     {% else %}
         {% if config.group_by_category %}
 
@@ -99,7 +127,7 @@
                 {% endif %}
                 {% with heading_level = heading_level + extra_level %}
                   {% for attribute in attributes|order_members(config.members_order, members_list) %}
-                    {% if not attribute.is_alias or attribute.is_explicitely_exported or attribute.inherited %}
+                    {% if members_list is not none or attribute.is_public(check_name=False) %}
                       {% include attribute|get_template with context %}
                     {% endif %}
                   {% endfor %}
@@ -119,7 +147,7 @@
                 {% endif %}
                 {% with heading_level = heading_level + extra_level %}
                   {% for class in classes|order_members(config.members_order, members_list) %}
-                    {% if not class.is_alias or class.is_explicitely_exported or class.inherited %}
+                    {% if members_list is not none or class.is_public(check_name=False) %}
                       {% include class|get_template with context %}
                     {% endif %}
                   {% endfor %}
@@ -140,7 +168,7 @@
                 {% with heading_level = heading_level + extra_level %}
                   {% for function in functions|order_members(config.members_order, members_list) %}
                     {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
-                      {% if not function.is_alias or function.is_explicitely_exported or function.inherited %}
+                      {% if members_list is not none or function.is_public(check_name=False) %}
                         {% include function|get_template with context %}
                       {% endif %}
                     {% endif %}
@@ -162,7 +190,7 @@
                   {% endif %}
                   {% with heading_level = heading_level + extra_level %}
                     {% for module in modules|order_members(config.members_order, members_list) %}
-                      {% if not module.is_alias or module.is_explicitely_exported or module.inherited %}
+                      {% if members_list is not none or module.is_public(check_name=False) %}
                         {% include module|get_template with context %}
                       {% endif %}
                     {% endfor %}
@@ -186,7 +214,7 @@
 
             {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %}
 
-              {% if not child.is_alias or child.is_explicitely_exported or child.inherited %}
+              {% if members_list is not none or child.is_public(check_name=False) %}
                 {% if child.is_attribute %}
                   {% with attribute = child %}
                     {% include attribute|get_template with context %}

docs/requirements.txt

@@ -30,11 +30,11 @@ mkdocs-mermaid2-plugin==1.1.1 ; python_version >= "3.8" and python_version < "4.
 mkdocs-section-index==0.3.9 ; python_version >= "3.8" and python_version < "4.0"
 mkdocs-spellcheck==1.1.0 ; python_version >= "3.8" and python_version < "4.0"
 mkdocstrings==0.25.1 ; python_version >= "3.8" and python_version < "4.0"
-mkdocstrings-python==1.10.0 ; python_version >= "3.8" and python_version < "4.0"
+mkdocstrings-python==1.10.2 ; python_version >= "3.8" and python_version < "4.0"
 mypy-extensions==1.0.0 ; python_version >= "3.8" and python_version < "4.0"
 packaging==24.0 ; python_version >= "3.8" and python_version < "4.0"
 pathspec==0.12.1 ; python_version >= "3.8" and python_version < "4.0"
-platformdirs==4.2.1 ; python_version >= "3.8" and python_version < "4.0"
+platformdirs==4.2.2 ; python_version >= "3.8" and python_version < "4.0"
 pygments==2.18.0 ; python_version >= "3.8" and python_version < "4.0"
 pymdown-extensions==10.8.1 ; python_version >= "3.8" and python_version < "4.0"
 python-dateutil==2.9.0.post0 ; python_version >= "3.8" and python_version < "4.0"
@@ -50,6 +50,6 @@ tomli==2.0.1 ; python_version >= "3.8" and python_version < "4.0"
 typing-extensions==4.11.0 ; python_version >= "3.8" and python_version < "3.11"
 urllib3==2.2.1 ; python_version >= "3.8" and python_version < "4.0"
 watchdog==4.0.0 ; python_version >= "3.8" and python_version < "4.0"
-wcmatch==8.5.1 ; python_version >= "3.8" and python_version < "4.0"
+wcmatch==8.5.2 ; python_version >= "3.8" and python_version < "4.0"
 wheel==0.43.0 ; python_version >= "3.8" and python_version < "3.9"
 zipp==3.18.1 ; python_version >= "3.8" and python_version < "3.10"

pyproject.toml

@@ -111,8 +111,8 @@ pre-commit = [
 ]
 pre-commit-update = "^0.3.0"
 pyclean = "^3.0.0"
-pylint = "3.1.0"
-pyright = "1.1.362"
+pylint = "3.2.0"
+pyright = "1.1.363"
 pyroma = "^4.2"
 python-semantic-release = "^9.6.0"
 ruff = "0.4.4"
@@ -140,7 +140,7 @@ mkdocs-mermaid2-plugin = "^1.1.1"
 mkdocs-section-index = "^0.3.9"
 mkdocs-spellcheck = "^1.1.0"
 mkdocstrings = "^0.25.0"
-mkdocstrings-python = "^1.10.0"
+mkdocstrings-python = "^1.10.2"
 pygments = "^2.17.2"
 pymdown-extensions = "^10.8.1"
 symspellpy = "^6.7.7"

src/tm_devices/helpers/constants_and_dataclasses.py

@@ -47,7 +47,7 @@ def __str__(self) -> str:
         for key, val in self.to_dict(ignore_none=True).items():
             # must pull class type from actual value, not the to_dict()'s representation
             if (
-                prefix := CONFIG_CLASS_STR_PREFIX_MAPPING.get(type(getattr(self, key)))
+                prefix := CONFIG_CLASS_STR_PREFIX_MAPPING.get(type(getattr(self, key)))  # pyright: ignore[reportUnknownArgumentType]
             ) is not None:
                 if any(val.values()):
                     # still need to ignore the None values