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..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 @@ -122,10 +124,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 a5f2328f..8be1c206 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,9 +3,9 @@ [build-system] requires = [ - "setuptools == 75.6.0", + "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,8 +54,8 @@ 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 - "pydoclint == 0.5.14", + "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml + "pydoclint == 0.6.0", "pydocstyle == 6.3.0", ] dev-formatting = ["black == 25.1.0", "isort == 5.13.2"] @@ -66,10 +66,10 @@ 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", - "frequenz-repo-config[lib] == 0.11.0", + "mkdocs-material == 9.6.2", + "mkdocstrings[python] == 0.28.0", + "mkdocstrings-python == 1.14.6", + "frequenz-repo-config[lib] == 0.12.2", ] dev-mypy = [ "mypy == 1.14.1", @@ -79,17 +79,17 @@ 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.3", + "pylint == 3.3.4", # For checking the noxfile, docs/ script, and tests "frequenz-client-microgrid[dev-mkdocs,dev-noxfile,dev-pytest]", ] 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.1", + "pytest-asyncio == 0.25.3", "async-solipsism == 0.7", ] dev = [ @@ -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"