From c1d64c57054b4542b5902719bda743d02d997af9 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 4 Feb 2025 09:48:41 +0000 Subject: [PATCH 1/3] Bump the required group across 1 directory with 7 updates Bumps the required group with 7 updates in the / directory: | Package | From | To | | --- | --- | --- | | [pydoclint](https://github.com/jsh9/pydoclint) | `0.5.14` | `0.6.0` | | [mkdocs-material](https://github.com/squidfunk/mkdocs-material) | `9.5.49` | `9.6.2` | | [mkdocstrings[python]](https://github.com/mkdocstrings/mkdocstrings) | `0.27.0` | `0.28.0` | | [mkdocstrings-python](https://github.com/mkdocstrings/python) | `1.13.0` | `1.14.3` | | [pylint](https://github.com/pylint-dev/pylint) | `3.3.3` | `3.3.4` | | [pytest-asyncio](https://github.com/pytest-dev/pytest-asyncio) | `0.25.1` | `0.25.3` | | [setuptools](https://github.com/pypa/setuptools) | `75.6.0` | `75.8.0` | Updates `pydoclint` from 0.5.14 to 0.6.0 - [Release notes](https://github.com/jsh9/pydoclint/releases) - [Changelog](https://github.com/jsh9/pydoclint/blob/main/CHANGELOG.md) - [Commits](https://github.com/jsh9/pydoclint/compare/0.5.14...0.6.0) Updates `mkdocs-material` from 9.5.49 to 9.6.2 - [Release notes](https://github.com/squidfunk/mkdocs-material/releases) - [Changelog](https://github.com/squidfunk/mkdocs-material/blob/master/CHANGELOG) - [Commits](https://github.com/squidfunk/mkdocs-material/compare/9.5.49...9.6.2) Updates `mkdocstrings[python]` from 0.27.0 to 0.28.0 - [Release notes](https://github.com/mkdocstrings/mkdocstrings/releases) - [Changelog](https://github.com/mkdocstrings/mkdocstrings/blob/main/CHANGELOG.md) - [Commits](https://github.com/mkdocstrings/mkdocstrings/compare/0.27.0...0.28.0) Updates `mkdocstrings-python` from 1.13.0 to 1.14.3 - [Release notes](https://github.com/mkdocstrings/python/releases) - [Changelog](https://github.com/mkdocstrings/python/blob/main/CHANGELOG.md) - [Commits](https://github.com/mkdocstrings/python/compare/1.13.0...1.14.3) Updates `pylint` from 3.3.3 to 3.3.4 - [Release notes](https://github.com/pylint-dev/pylint/releases) - [Commits](https://github.com/pylint-dev/pylint/compare/v3.3.3...v3.3.4) Updates `pytest-asyncio` from 0.25.1 to 0.25.3 - [Release notes](https://github.com/pytest-dev/pytest-asyncio/releases) - [Commits](https://github.com/pytest-dev/pytest-asyncio/compare/v0.25.1...v0.25.3) Updates `setuptools` from 75.6.0 to 75.8.0 - [Release notes](https://github.com/pypa/setuptools/releases) - [Changelog](https://github.com/pypa/setuptools/blob/main/NEWS.rst) - [Commits](https://github.com/pypa/setuptools/compare/v75.6.0...v75.8.0) --- updated-dependencies: - dependency-name: pydoclint dependency-type: direct:production update-type: version-update:semver-minor dependency-group: required - dependency-name: mkdocs-material dependency-type: direct:production update-type: version-update:semver-minor dependency-group: required - dependency-name: mkdocstrings[python] dependency-type: direct:production update-type: version-update:semver-minor dependency-group: required - dependency-name: mkdocstrings-python dependency-type: direct:production update-type: version-update:semver-minor dependency-group: required - dependency-name: pylint dependency-type: direct:production update-type: version-update:semver-patch dependency-group: required - dependency-name: pytest-asyncio dependency-type: direct:production update-type: version-update:semver-patch dependency-group: required - dependency-name: setuptools dependency-type: direct:production update-type: version-update:semver-minor dependency-group: required ... Signed-off-by: dependabot[bot] --- pyproject.toml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index a5f2328f..4976e030 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ [build-system] requires = [ - "setuptools == 75.6.0", + "setuptools == 75.8.0", "setuptools_scm[toml] == 8.1.0", "frequenz-repo-config[lib] == 0.11.0", ] @@ -55,7 +55,7 @@ dev-flake8 = [ "flake8 == 7.1.1", "flake8-docstrings == 1.7.0", "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml - "pydoclint == 0.5.14", + "pydoclint == 0.6.0", "pydocstyle == 6.3.0", ] dev-formatting = ["black == 25.1.0", "isort == 5.13.2"] @@ -66,9 +66,9 @@ dev-mkdocs = [ "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.3.7", - "mkdocs-material == 9.5.49", - "mkdocstrings[python] == 0.27.0", - "mkdocstrings-python == 1.13.0", + "mkdocs-material == 9.6.2", + "mkdocstrings[python] == 0.28.0", + "mkdocstrings-python == 1.14.3", "frequenz-repo-config[lib] == 0.11.0", ] dev-mypy = [ @@ -81,7 +81,7 @@ dev-mypy = [ ] dev-noxfile = ["nox == 2024.10.9", "frequenz-repo-config[lib] == 0.11.0"] dev-pylint = [ - "pylint == 3.3.3", + "pylint == 3.3.4", # For checking the noxfile, docs/ script, and tests "frequenz-client-microgrid[dev-mkdocs,dev-noxfile,dev-pytest]", ] @@ -89,7 +89,7 @@ dev-pytest = [ "pytest == 8.3.4", "frequenz-repo-config[extra-lint-examples] == 0.11.0", "pytest-mock == 3.14.0", - "pytest-asyncio == 0.25.1", + "pytest-asyncio == 0.25.3", "async-solipsism == 0.7", ] dev = [ From 83d15a43e3dc2279b1ec2c90cef80db3d4cb1382 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 10 Feb 2025 15:12:32 +0100 Subject: [PATCH 2/3] Upgrade to repo-config v0.12.2 Signed-off-by: Leandro Lucarella --- docs/_scripts/macros.py | 81 ----------------------------------------- mkdocs.yml | 5 +-- pyproject.toml | 13 ++++--- 3 files changed, 9 insertions(+), 90 deletions(-) delete mode 100644 docs/_scripts/macros.py diff --git a/docs/_scripts/macros.py b/docs/_scripts/macros.py deleted file mode 100644 index 4a7dc10b..00000000 --- a/docs/_scripts/macros.py +++ /dev/null @@ -1,81 +0,0 @@ -# License: MIT -# Copyright © 2024 Frequenz Energy-as-a-Service GmbH - -"""This module defines macros for use in Markdown files.""" - -from typing import Any - -import markdown as md -from markdown.extensions import toc -from mkdocs_macros import plugin as macros - -_CODE_ANNOTATION_MARKER: str = ( - r'' - r'' - r'' - r"" - r"" -) - - -def _slugify(text: str) -> str: - """Slugify a text. - - Args: - text: The text to slugify. - - Returns: - The slugified text. - """ - return toc.slugify_unicode(text, "-") - - -def _hook_macros_plugin(env: macros.MacrosPlugin) -> None: - """Integrate the `mkdocs-macros` plugin into `mkdocstrings`. - - This is a temporary workaround to make `mkdocs-macros` work with - `mkdocstrings` until a proper `mkdocs-macros` *pluglet* is available. See - https://github.com/mkdocstrings/mkdocstrings/issues/615 for details. - - Args: - env: The environment to hook the plugin into. - """ - # get mkdocstrings' Python handler - python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python") - - # get the `update_env` method of the Python handler - update_env = python_handler.update_env - - # override the `update_env` method of the Python handler - def patched_update_env(markdown: md.Markdown, config: dict[str, Any]) -> None: - update_env(markdown, config) - - # get the `convert_markdown` filter of the env - convert_markdown = python_handler.env.filters["convert_markdown"] - - # build a chimera made of macros+mkdocstrings - def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any: - return convert_markdown(env.render(markdown), *args, **kwargs) - - # patch the filter - python_handler.env.filters["convert_markdown"] = render_convert - - # patch the method - python_handler.update_env = patched_update_env - - -def define_env(env: macros.MacrosPlugin) -> None: - """Define the hook to create macro functions for use in Markdown. - - Args: - env: The environment to define the macro functions in. - """ - # A variable to easily show an example code annotation from mkdocs-material. - # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations - env.variables["code_annotation_marker"] = _CODE_ANNOTATION_MARKER - - # To add any other macros, variables and filters, do it here (before the call to - # _hook_macros_plugin()). - - # This hook needs to be done at the end of the `define_env` function. - _hook_macros_plugin(env) diff --git a/mkdocs.yml b/mkdocs.yml index 7fba1fb8..8c9fc5b0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -122,10 +122,9 @@ plugins: - https://grpc.github.io/grpc/python/objects.inv - https://typing-extensions.readthedocs.io/en/stable/objects.inv # Note this plugin must be loaded after mkdocstrings to be able to use macros - # inside docstrings. See the comment in `docs/_scripts/macros.py` for more - # details + # inside docstrings. - macros: - module_name: docs/_scripts/macros + modules: ["frequenz.repo.config.mkdocs.mkdocstrings_macros"] on_undefined: strict on_error_fail: true - search diff --git a/pyproject.toml b/pyproject.toml index 4976e030..8be1c206 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ requires = [ "setuptools == 75.8.0", "setuptools_scm[toml] == 8.1.0", - "frequenz-repo-config[lib] == 0.11.0", + "frequenz-repo-config[lib] == 0.12.2", ] build-backend = "setuptools.build_meta" @@ -54,7 +54,7 @@ email = "floss@frequenz.com" dev-flake8 = [ "flake8 == 7.1.1", "flake8-docstrings == 1.7.0", - "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml + "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml "pydoclint == 0.6.0", "pydocstyle == 6.3.0", ] @@ -68,8 +68,8 @@ dev-mkdocs = [ "mkdocs-macros-plugin == 1.3.7", "mkdocs-material == 9.6.2", "mkdocstrings[python] == 0.28.0", - "mkdocstrings-python == 1.14.3", - "frequenz-repo-config[lib] == 0.11.0", + "mkdocstrings-python == 1.14.6", + "frequenz-repo-config[lib] == 0.12.2", ] dev-mypy = [ "mypy == 1.14.1", @@ -79,7 +79,7 @@ dev-mypy = [ # For checking the noxfile, docs/ script, and tests "frequenz-client-microgrid[dev-mkdocs,dev-noxfile,dev-pytest]", ] -dev-noxfile = ["nox == 2024.10.9", "frequenz-repo-config[lib] == 0.11.0"] +dev-noxfile = ["nox == 2024.10.9", "frequenz-repo-config[lib] == 0.12.2"] dev-pylint = [ "pylint == 3.3.4", # For checking the noxfile, docs/ script, and tests @@ -87,7 +87,7 @@ dev-pylint = [ ] dev-pytest = [ "pytest == 8.3.4", - "frequenz-repo-config[extra-lint-examples] == 0.11.0", + "frequenz-repo-config[extra-lint-examples] == 0.12.2", "pytest-mock == 3.14.0", "pytest-asyncio == 0.25.3", "async-solipsism == 0.7", @@ -161,6 +161,7 @@ disable = [ ] [tool.pytest.ini_options] +addopts = "-W=all -Werror -Wdefault::DeprecationWarning -Wdefault::PendingDeprecationWarning -vv" testpaths = ["tests", "src"] asyncio_mode = "auto" asyncio_default_fixture_loop_scope = "function" From 1aab7b5cc874dba8bcd53c42842e78c17402a62e Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Tue, 11 Feb 2025 14:45:37 +0100 Subject: [PATCH 3/3] Enable autorefs plugin option to resolve closest references The new version of the plugin will warn if there are multiple references to the same object, for example: ``` WARNING - mkdocs_autorefs: Multiple secondary URLs found for 'frequenz.client.base.exception.ApiClientError.description': ['reference/frequenz/client/microgrid/#frequenz.client.microgrid.ApiClientError.description', 'reference/frequenz/client/microgrid/#frequenz.client.microgrid.ClientNotConnected.description']. ``` To avoid this we enable the `resolve_closest` option: https://mkdocstrings.github.io/autorefs/#non-unique-headings But this looks like a bug in the plugin, so we'll see: https://github.com/mkdocstrings/autorefs/issues/52#issuecomment-2650901481 Signed-off-by: Leandro Lucarella --- mkdocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 8c9fc5b0..c1d52074 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -87,6 +87,8 @@ markdown_extensions: permalink: "¤" plugins: + - autorefs: + resolve_closest: true - gen-files: scripts: - docs/_scripts/mkdocstrings_autoapi.py