Add mgration script

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

Author: llucax

cookiecutter/migrate.py

@@ -20,6 +20,7 @@
 And remember to follow any manual instructions for each run.
 """  # noqa: E501
 
+import hashlib
 import os
 import subprocess
 import tempfile
@@ -30,8 +31,8 @@
 def main() -> None:
     """Run the migration steps."""
     add_default_pytest_options()
-
-    # Add a separation line like this one after each migration step.
+    print("=" * 72)
+    migrate_mkdocs_macros()
     print("=" * 72)
 
 
@@ -64,6 +65,92 @@ def add_default_pytest_options() -> None:
     )
 
 
+def migrate_mkdocs_macros() -> None:
+    """Migrate from custom macros.py to standard module."""
+    macros_file = Path("docs/_scripts/macros.py")
+    mkdocs_yaml = Path("mkdocs.yaml")
+    if not mkdocs_yaml.exists():
+        mkdocs_yaml = Path("mkdocs.yml")
+
+    known_hashes = {
+        "47a991286132471b6cb666577beb89e78c0f5d4975c53f0dcb319c4338a2c3cb",
+        "6bb960c72b370ac77918f49d7a35f39c0ddb58fe52cf2d12caa2577098fd8469",
+        "7351276ac314955a343bab09d1602e50300887291f841643e9fb79c94acc923c",
+        "8fa5f9f3fd928e17f590e3ab056434474633259d615971404db0d2f3034adb62",
+        "ba3ff5f1612b3dd22372a8ca95394b8ea468f18dcefc494c73811c8433fcb880",
+        "dd32e8759abc43232bb3db5b33c0a7cf8d8442db6135c594968c499d8bae0ce5",
+    }
+
+    print("Checking if docs/_scripts/macros.py can be migrated...")
+
+    file_hash = calculate_file_sha256_skip_lines(macros_file, 2)
+    if not file_hash:
+        return
+
+    if file_hash not in known_hashes:
+        manual_step("The macros.py file seems to be customized. You have two options:")
+        manual_step("")
+        manual_step(
+            "1. Switch to the standard module (if you don't have custom macros):"
+        )
+        manual_step("   a. Update mkdocs.yaml to use the standard module:")
+        manual_step(
+            '      module_name: docs/_scripts/macros -> modules: ["frequenz.repo.config.mkdocs.mkdocstrings_macros"]'  # noqa: E501
+        )
+        manual_step("   b. Remove docs/_scripts/macros.py")
+        manual_step("")
+        manual_step("2. Keep your custom macros but use the standard functionality:")
+        manual_step("   a. Update mkdocs.yaml:")
+        manual_step("      - Keep using module_name: docs/_scripts/macros")
+        manual_step("   b. Update your macros.py to be minimal:")
+        manual_step("      ```python")
+        manual_step(
+            "      from frequenz.repo.config.mkdocs.mkdocstrings_macros import hook_env_with_everything"  # noqa: E501
+        )
+        manual_step("")
+        manual_step("      def define_env(env):")
+        manual_step("          # Add your custom variables, filters, and macros here")
+        manual_step("          env.variables.my_var = 'Example'")
+        manual_step("          env.filters.my_filter = lambda x: x.upper()")
+        manual_step("")
+        manual_step(
+            "          # This must be at the end to enable all standard features"
+        )
+        manual_step("          hook_env_with_everything(env)")
+        manual_step("      ```")
+        manual_step("")
+        manual_step("See the docs for more details:")
+        manual_step(
+            "https://frequenz-floss.github.io/frequenz-repo-config-python/v0.12/reference/frequenz/repo/config/mkdocs/mkdocstrings_macros/"  # noqa: E501
+        )
+        return
+
+    if not mkdocs_yaml.exists():
+        print("mkdocs.yaml/yml not found, skipping macros migration")
+        return
+
+    content = mkdocs_yaml.read_text(encoding="utf-8")
+    if "module_name: docs/_scripts/macros" not in content:
+        print("Custom macros configuration not found in mkdocs.yaml")
+        return
+
+    print("Updating mkdocs.yaml to use standard module...")
+    new_content = content.replace(
+        "module_name: docs/_scripts/macros",
+        'modules: ["frequenz.repo.config.mkdocs.mkdocstrings_macros"]',
+    )
+    new_content = new_content.replace(
+        "# inside docstrings. See the comment in `docs/_scripts/macros.py` for more\n"
+        "  # details\n",
+        "# inside docstrings.\n",
+    )
+
+    replace_file_contents_atomically(mkdocs_yaml, content, new_content)
+
+    print("Removing docs/_scripts/macros.py...")
+    macros_file.unlink()
+
+
 def apply_patch(patch_content: str) -> None:
     """Apply a patch using the patch utility."""
     subprocess.run(["patch", "-p1"], input=patch_content.encode(), check=True)
@@ -134,5 +221,25 @@ def manual_step(message: str) -> None:
     print(f"\033[0;33m>>> {message}\033[0m")
 
 
+def calculate_file_sha256_skip_lines(filepath: Path, skip_lines: int) -> str | None:
+    """Calculate SHA256 of file contents excluding the first N lines.
+
+    Args:
+        filepath: Path to the file to hash
+        skip_lines: Number of lines to skip at the beginning
+
+    Returns:
+        The SHA256 hex digest, or None if the file doesn't exist
+    """
+    if not filepath.exists():
+        return None
+
+    # Read file and normalize line endings to LF
+    content = filepath.read_text(encoding="utf-8").replace("\r\n", "\n")
+    # Skip first N lines and ensure there's a trailing newline
+    remaining_content = "\n".join(content.splitlines()[skip_lines:]) + "\n"
+    return hashlib.sha256(remaining_content.encode()).hexdigest()
+
+
 if __name__ == "__main__":
     main()

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

@@ -0,0 +1,80 @@
+# License: {{cookiecutter.license}}
+# Copyright © {{copyright_year}} {{cookiecutter.author_name}}
+
+"""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'<span class="md-annotation">'
+    r'<span class="md-annotation__index" tabindex="-1">'
+    r'<span data-md-annotation-id="1"></span>'
+    r"</span>"
+    r"</span>"
+)
+
+
+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
+
+    # 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

@@ -0,0 +1,108 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""This module defines macros for use in Markdown files."""
+
+import logging
+from typing import Any
+
+import markdown as md
+from markdown.extensions import toc
+from mkdocs_macros import plugin as macros
+
+from frequenz.repo.config import github
+
+_logger = logging.getLogger(__name__)
+
+_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>"
+)
+
+
+def _slugify(text: str) -> str:
+    """Slugify a text.
+
+    Args:
+        text: The text to slugify.
+
+    Returns:
+        The slugified text.
+    """
+    return toc.slugify_unicode(text, "-")
+
+
+def _add_version_variables(env: macros.MacrosPlugin) -> None:
+    """Add variables with git information to the environment.
+
+    Args:
+        env: The environment to add the variables to.
+    """
+    env.variables["version"] = None
+    env.variables["version_requirement"] = ""
+    try:
+        version_info = github.get_repo_version_info()
+    except Exception as exc:  # pylint: disable=broad-except
+        _logger.warning("Failed to get version info: %s", exc)
+    else:
+        env.variables["version"] = version_info
+        if version_info.current_tag:
+            env.variables["version_requirement"] = f" == {version_info.current_tag}"
+        elif version_info.current_branch:
+            env.variables["version_requirement"] = (
+                " @ git+https://github.com/frequenz-floss/frequenz-repo-config-python"
+                f"@{version_info.current_branch}"
+            )
+
+
+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
+
+    _add_version_variables(env)
+
+    # This hook needs to be done at the end of the `define_env` function.
+    _hook_macros_plugin(env)