Move the hooking of mkdocstrings and macros to a function

This code is pure noise for users in the `define_env()` function, so we
abstract it away and move it into its own function so the noise is
reduced to the minimum.

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

Author: llucax

cookiecutter/{{cookiecutter.github_repo_name}}/docs/_scripts/macros.py

@@ -33,22 +33,16 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
-def define_env(env: macros.MacrosPlugin) -> None:
-    """Define the hook to create macro functions for use in Markdown.
+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 define the macro functions in.
+        env: The environment to hook the plugin into.
     """
-    # 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
-
-    # TODO(cookiecutter): Add any other macros, variables and filters here.
-
-    # The code below 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.
-
     # get mkdocstrings' Python handler
     python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
 
@@ -71,3 +65,19 @@ def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
 
     # 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
+
+    # TODO(cookiecutter): Add any other macros, variables and filters here.
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)

docs/_scripts/macros.py

@@ -33,20 +33,16 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
-def define_env(env: macros.MacrosPlugin) -> None:
-    """Define the hook to create macro functions for use in Markdown.
+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 define the macro functions in.
+        env: The environment to hook the plugin into.
     """
-    # 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
-
-    # The code below 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.
-
     # get mkdocstrings' Python handler
     python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
 
@@ -69,3 +65,17 @@ def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
 
     # 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
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/docs/_scripts/macros.py

@@ -33,22 +33,16 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
-def define_env(env: macros.MacrosPlugin) -> None:
-    """Define the hook to create macro functions for use in Markdown.
+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 define the macro functions in.
+        env: The environment to hook the plugin into.
     """
-    # 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
-
-    # TODO(cookiecutter): Add any other macros, variables and filters here.
-
-    # The code below 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.
-
     # get mkdocstrings' Python handler
     python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
 
@@ -71,3 +65,19 @@ def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
 
     # 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
+
+    # TODO(cookiecutter): Add any other macros, variables and filters here.
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/docs/_scripts/macros.py

@@ -33,22 +33,16 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
-def define_env(env: macros.MacrosPlugin) -> None:
-    """Define the hook to create macro functions for use in Markdown.
+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 define the macro functions in.
+        env: The environment to hook the plugin into.
     """
-    # 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
-
-    # TODO(cookiecutter): Add any other macros, variables and filters here.
-
-    # The code below 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.
-
     # get mkdocstrings' Python handler
     python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
 
@@ -71,3 +65,19 @@ def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
 
     # 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
+
+    # TODO(cookiecutter): Add any other macros, variables and filters here.
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)

tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/docs/_scripts/macros.py

@@ -33,22 +33,16 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
-def define_env(env: macros.MacrosPlugin) -> None:
-    """Define the hook to create macro functions for use in Markdown.
+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 define the macro functions in.
+        env: The environment to hook the plugin into.
     """
-    # 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
-
-    # TODO(cookiecutter): Add any other macros, variables and filters here.
-
-    # The code below 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.
-
     # get mkdocstrings' Python handler
     python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
 
@@ -71,3 +65,19 @@ def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
 
     # 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
+
+    # TODO(cookiecutter): Add any other macros, variables and filters here.
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)

tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/docs/_scripts/macros.py

@@ -33,22 +33,16 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
-def define_env(env: macros.MacrosPlugin) -> None:
-    """Define the hook to create macro functions for use in Markdown.
+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 define the macro functions in.
+        env: The environment to hook the plugin into.
     """
-    # 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
-
-    # TODO(cookiecutter): Add any other macros, variables and filters here.
-
-    # The code below 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.
-
     # get mkdocstrings' Python handler
     python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
 
@@ -71,3 +65,19 @@ def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
 
     # 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
+
+    # TODO(cookiecutter): Add any other macros, variables and filters here.
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)

tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/docs/_scripts/macros.py

@@ -33,22 +33,16 @@ def _slugify(text: str) -> str:
     return toc.slugify_unicode(text, "-")  # type: ignore[attr-defined,no-any-return]
 
 
-def define_env(env: macros.MacrosPlugin) -> None:
-    """Define the hook to create macro functions for use in Markdown.
+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 define the macro functions in.
+        env: The environment to hook the plugin into.
     """
-    # 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
-
-    # TODO(cookiecutter): Add any other macros, variables and filters here.
-
-    # The code below 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.
-
     # get mkdocstrings' Python handler
     python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
 
@@ -71,3 +65,19 @@ def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
 
     # 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
+
+    # TODO(cookiecutter): Add any other macros, variables and filters here.
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)