From 2c568f1f6f66c3dd46ed16a46564e800a87311e9 Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Wed, 15 May 2024 16:42:22 -0700 Subject: [PATCH 1/4] docs: Update API template to use the new jinja template format. --- .pre-commit-config.yaml | 11 ++++++- .../{children.html => children.html.jinja} | 31 ++++++++++++++----- docs/requirements.txt | 6 ++-- pyproject.toml | 6 ++-- 4 files changed, 40 insertions(+), 14 deletions(-) rename docs/_templates/mkdocstrings/python/readthedocs/{children.html => children.html.jinja} (88%) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7a0e60ed..6b3be3cc 100644 --- a/.pre-commit-config.yaml +++ b/.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: diff --git a/docs/_templates/mkdocstrings/python/readthedocs/children.html b/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja similarity index 88% rename from docs/_templates/mkdocstrings/python/readthedocs/children.html rename to docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja index abe3f818..120ab3a5 100644 --- a/docs/_templates/mkdocstrings/python/readthedocs/children.html +++ b/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#} +{#- 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. +-#} +{# Original source file: https://github.com/mkdocstrings/python/blob/main/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja#} {%- macro create_summary_table(item_list) -%} @@ -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 %}
@@ -99,7 +116,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 +136,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 +157,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 +179,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 +203,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 %} diff --git a/docs/requirements.txt b/docs/requirements.txt index f9fbba8e..8f992699 100644 --- a/docs/requirements.txt +++ b/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" diff --git a/pyproject.toml b/pyproject.toml index 4d08662c..8040cfb2 100644 --- a/pyproject.toml +++ b/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" From ee33e89c07b81a42140bdb8584c56a6df15db8d1 Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Wed, 15 May 2024 16:50:59 -0700 Subject: [PATCH 2/4] docs: Update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a2cd8875..08fe5486 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,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. --- From cf238f66189e06f8a29365e82738f85408f06f81 Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Wed, 15 May 2024 17:05:05 -0700 Subject: [PATCH 3/4] refactor: fix build issues --- .../mkdocstrings/python/readthedocs/children.html.jinja | 2 +- src/tm_devices/helpers/constants_and_dataclasses.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja b/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja index 120ab3a5..96cb66cc 100644 --- a/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja +++ b/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja @@ -1,3 +1,4 @@ +{# 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. @@ -9,7 +10,6 @@ Context: root_members (bool): Whether the object is the root object. heading_level (int): The HTML heading level to use. -#} -{# Original source file: https://github.com/mkdocstrings/python/blob/main/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja#} {%- macro create_summary_table(item_list) -%}
diff --git a/src/tm_devices/helpers/constants_and_dataclasses.py b/src/tm_devices/helpers/constants_and_dataclasses.py index afaae31f..308611cb 100644 --- a/src/tm_devices/helpers/constants_and_dataclasses.py +++ b/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 From b63056ca0c9ec99f0ca32cfd7bc19a1af6706aee Mon Sep 17 00:00:00 2001 From: Nicholas Felt Date: Thu, 16 May 2024 08:37:41 -0700 Subject: [PATCH 4/4] docs: Added a section that shows the submodules of each subpackage in the summary --- CHANGELOG.md | 4 ++++ .../python/readthedocs/children.html.jinja | 11 +++++++++++ 2 files changed, 15 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 08fe5486..36760992 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja b/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja index 96cb66cc..6fd5c88e 100644 --- a/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja +++ b/docs/_templates/mkdocstrings/python/readthedocs/children.html.jinja @@ -93,6 +93,17 @@ Context: {{ 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 %}