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()