Fix the mkdocstrings-macros pluglet (#352)

The new mkdocstrings-macros *pluglet* didn't work with the latest
`mkdocstrings-python` version.

To fix this we need to require a newer version of `mkdocstrings-python`
and update the `mkdocstrings_macros.py` file to work with the new
version.

Author: llucax

.github/cookiecutter-migrate.template.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
@@ -98,6 +99,26 @@ def replace_file_contents_atomically(  # noqa; DOC501
         raise
 
 
+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()
+
+
 def manual_step(message: str) -> None:
     """Print a manual step message in yellow."""
     print(f"\033[0;33m>>> {message}\033[0m")

.github/workflows/ci.yaml

@@ -197,7 +197,7 @@ jobs:
       # This ensures that the runner has access to the pip cache.
       - name: Reset pip cache ownership
         if: always()
-        run: sudo chown -R $USER:$USER /tmp/pip-cache
+        run: if [[ -e /tmp/pip-cache ]]; then sudo chown -R $USER:$USER /tmp/pip-cache; fi
 
   # This job runs if all the `nox-cross-arch` matrix jobs ran and succeeded.
   # As the `nox-all` job, its main purpose is to provide a single point of

RELEASE_NOTES.md

@@ -1,42 +1,9 @@
 # Frequenz Repository Configuration Release Notes
 
-## Summary
-
-This release introduces a new MkDocs macros *pluglet* system that simplifies documentation setup and provides enhanced functionality for version information and code annotations. It also includes changes to how pytest warnings are handled in templates.
-
 ## Upgrading
 
-- The `nox` default `pytest` session doesn't pass `-W=all -vv` to `pytest` anymore. You can use the `pyproject.toml` file to configure default options for `pytest`, for example:
-
-    ```toml
-    [tool.pytest.ini_options]
-    addopts = "-W=all -Werror -Wdefault::DeprecationWarning -Wdefault::PendingDeprecationWarning -vv"
-    ```
-
-### Cookiecutter template
-
-All upgrading should be done via the migration script or regenerating the templates.
-
-```bash
-curl -sSL https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/v0.12/cookiecutter/migrate.py | python3
-```
-
-But you might still need to adapt your code:
-
-- `pytest` now uses `-Werror` by default (but still treat deprecations as normal warnings), so if your tests run with warnings, they will now be turned to errors, and you'll need to fix them.
-
-- Projects using `docs/_scripts/macros.py` with customized scripts can use the new provided utility functions. See the [`mkdocstrings_macros` documentation](https://frequenz-floss.github.io/frequenz-repo-config-python/v0.12/reference/frequenz/repo/config/mkdocs/mkdocstrings_macros/) for the new features and setup.
-
-## New Features
-
-- Two new modules were introduced to facilitate the configuration of `macros` for use within docstrings via `mkdocstrings`: [`mkdocstrings_macros`](https://frequenz-floss.github.io/frequenz-repo-config-python/v0.12/reference/frequenz/repo/config/mkdocs/mkdocstrings_macros/) and [`annotations`](https://frequenz-floss.github.io/frequenz-repo-config-python/v0.12/reference/frequenz/repo/config/mkdocs/annotations/).
-
-### Cookiecutter template
-
-- `pytest` now uses `-Werror -Wdefault::DeprecationWarning -Wdefault::PendingDeprecationWarning` by default. Deprecations are still treated as warnings, as when testing with the `pytest_min` session is normal to get deprecation warnings as we are using old versions of dependencies.
+Even if this is a patch release, it will require a dependency bump for `mkdocstrings-python` to v1.14.6 or newer, but since these are only dev dependencies and things will break if you update the dependencies anyway, it seems like a reasonable trade-off.
 
 ## Bug Fixes
 
-### Cookiecutter template
-
-- Fixed a compatibility issue in the macros doc script with `mkdocsstrings` 0.28.
+- The new mkdocstrings-macros *pluglet* didn't work with the latest `mkdocstrings-python` version.

cookiecutter/migrate.py

@@ -30,125 +30,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)
-
-
-def add_default_pytest_options() -> None:
-    """Add default pytest options to pyproject.toml."""
-    pyproject_toml = Path("pyproject.toml")
-    pyproject_toml_content = pyproject_toml.read_text(encoding="utf-8")
-    marker = "[tool.pytest.ini_options]\n"
-    new_options = (
-        "-W=all -Werror -Wdefault::DeprecationWarning "
-        "-Wdefault::PendingDeprecationWarning -vv"
-    )
-
-    print(f"Adding default pytest options to {pyproject_toml}...")
-    if pyproject_toml_content.find(marker) == -1:
-        print(
-            "Couldn't find the the {marker.strip()} marker in pyproject.toml, skipping update."
-        )
-        return
-
-    if pyproject_toml_content.find("\naddopts") >= 0:
-        print("It looks like some options are already configured, skipping update.")
-        manual_step(f"Please consider `{new_options}` if they are not there yet.")
-        return
-
-    replace_file_contents_atomically(
-        pyproject_toml,
-        marker,
-        marker + f'addopts = "{new_options}"\n',
-    )
-
-
-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:
@@ -216,11 +99,6 @@ def replace_file_contents_atomically(  # noqa; DOC501
         raise
 
 
-def manual_step(message: str) -> None:
-    """Print a manual step message in yellow."""
-    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.
 
@@ -241,5 +119,10 @@ def calculate_file_sha256_skip_lines(filepath: Path, skip_lines: int) -> str | N
     return hashlib.sha256(remaining_content.encode()).hexdigest()
 
 
+def manual_step(message: str) -> None:
+    """Print a manual step message in yellow."""
+    print(f"\033[0;33m>>> {message}\033[0m")
+
+
 if __name__ == "__main__":
     main()

cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml

@@ -100,7 +100,7 @@ dev-mkdocs = [
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.2",
   "mkdocstrings[python] == 0.28.0",
-  "mkdocstrings-python == 1.14.0",
+  "mkdocstrings-python == 1.14.6",
   "frequenz-repo-config[{{cookiecutter.type}}] == 0.12.0",
 ]
 dev-mypy = [

pyproject.toml

@@ -41,6 +41,7 @@ dependencies = [
   "mkdocs-gen-files >= 0.4.0, < 0.6.0",
   "semver >= 3.0.1, < 4",
   "github-action-utils >= 1.1.0, < 2",
+  "mkdocstrings-python >= 1.14.6, < 2",
 ]
 dynamic = ["version"]
 
@@ -83,7 +84,7 @@ dev-mkdocs = [
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.2",
   "mkdocstrings[python] == 0.28.0",
-  "mkdocstrings-python == 1.13.0",
+  "mkdocstrings-python == 1.14.6",
 ]
 dev-mypy = [
   "mypy == 1.14.1",

src/frequenz/repo/config/mkdocs/mkdocstrings_macros.py

@@ -112,7 +112,6 @@ def define_env(env: macros.MacrosPlugin) -> None:
 import logging
 from typing import Any
 
-import markdown as md
 from markdown.extensions import toc
 from mkdocs_macros import plugin as macros
 
@@ -210,8 +209,8 @@ def hook_macros_plugin(env: macros.MacrosPlugin) -> None:
     update_env = python_handler.update_env
 
     # override the `update_env` method of the Python handler
-    def patched_update_env(md: md.Markdown, config: dict[str, Any]) -> None:
-        update_env(md, config)
+    def patched_update_env(config: dict[str, Any]) -> None:
+        update_env(config=config)
 
         # get the `convert_markdown` filter of the env
         convert_markdown = python_handler.env.filters["convert_markdown"]

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml

@@ -59,7 +59,7 @@ dev-mkdocs = [
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.2",
   "mkdocstrings[python] == 0.28.0",
-  "mkdocstrings-python == 1.14.0",
+  "mkdocstrings-python == 1.14.6",
   "frequenz-repo-config[actor] == 0.12.0",
 ]
 dev-mypy = [

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/pyproject.toml

@@ -70,7 +70,7 @@ dev-mkdocs = [
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.2",
   "mkdocstrings[python] == 0.28.0",
-  "mkdocstrings-python == 1.14.0",
+  "mkdocstrings-python == 1.14.6",
   "frequenz-repo-config[api] == 0.12.0",
 ]
 dev-mypy = [

tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/pyproject.toml

@@ -58,7 +58,7 @@ dev-mkdocs = [
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.2",
   "mkdocstrings[python] == 0.28.0",
-  "mkdocstrings-python == 1.14.0",
+  "mkdocstrings-python == 1.14.6",
   "frequenz-repo-config[app] == 0.12.0",
 ]
 dev-mypy = [

tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/pyproject.toml

@@ -55,7 +55,7 @@ dev-mkdocs = [
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.2",
   "mkdocstrings[python] == 0.28.0",
-  "mkdocstrings-python == 1.14.0",
+  "mkdocstrings-python == 1.14.6",
   "frequenz-repo-config[lib] == 0.12.0",
 ]
 dev-mypy = [

tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/pyproject.toml

@@ -59,7 +59,7 @@ dev-mkdocs = [
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.2",
   "mkdocstrings[python] == 0.28.0",
-  "mkdocstrings-python == 1.14.0",
+  "mkdocstrings-python == 1.14.6",
   "frequenz-repo-config[model] == 0.12.0",
 ]
 dev-mypy = [