Simplify macros script

We now use the new much simpler macros hooks in repo-config v0.12.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

docs/_scripts/macros.py

@@ -5,65 +5,12 @@
 
 import os
 import pathlib
-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'<span class="md-annotation">'
-    r'<span class="md-annotation__index" tabindex="-1">'
-    r'<span data-md-annotation-id="1"></span>'
-    r"</span>"
-    r"</span>"
+from frequenz.repo.config.mkdocs.mkdocstrings_macros import (
+    hook_env_with_everything,
+    slugify,
 )
-
-
-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
+from mkdocs_macros import plugin as macros
 
 
 def define_env(env: macros.MacrosPlugin) -> None:
@@ -72,9 +19,6 @@ def define_env(env: macros.MacrosPlugin) -> None:
     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
 
     @env.macro  # type: ignore[misc]
     def glossary(term: str, text: str | None = None) -> str:
@@ -94,7 +38,7 @@ def glossary(term: str, text: str | None = None) -> str:
         # always the case, for example when referencing the glossary from the API
         # reference.
         link_path = os.path.relpath(glossary_path, current_path.parent)
-        return f"[{text or term}]({link_path}#{_slugify(term)})"
+        return f"[{text or term}]({link_path}#{slugify(term)})"
 
-    # This hook needs to be done at the end of the `define_env` function.
-    _hook_macros_plugin(env)
+    # This must be at the end to enable all standard features
+    hook_env_with_everything(env)