Fix wrongly located paths key in mkdocs.yml

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Author: llucax

RELEASE_NOTES.md

@@ -34,4 +34,4 @@ But you might still need to adapt your code:
 
 ### Cookiecutter template
 
-<!-- Here bug fixes for cookiecutter specifically -->
+- mkdocstrings: Move `paths` key to the rigth section in `mkdocs.yml`.

cookiecutter/migrate.py

@@ -39,10 +39,74 @@ def main() -> None:
         "mkdocs.yml", "          import:", "          inventories:"
     )
     print("=" * 72)
+    print("Fixing wrongly located `paths` keys in mkdocs.yml...")
+    migrate_mkdocs_yaml(Path("mkdocs.yml"))
+    print("=" * 72)
     print("Migration script finished. Remember to follow any manual instructions.")
     print("=" * 72)
 
 
+def migrate_mkdocs_yaml(file_path: Path) -> None:
+    """
+    Inspect a mkdocs.yml file textually and, if it defines `paths` under
+    `plugins: -> mkdocstrings: -> handlers: -> python: -> options:`,
+    rewrite the file in place to move `paths` directly under `python:`
+    and remove the old `options:` and its `paths:` line. This uses only
+    line-based detection (no external dependencies).
+
+    Args:
+        file_path: Path to the mkdocs.yml file to migrate.
+    """
+    if not file_path.is_file():
+        return
+
+    lines = file_path.read_text(encoding="utf-8").splitlines(keepends=True)
+    needs_migration = False
+    in_python = False
+    in_options = False
+
+    # 1) Detect whether there's a "        python:" followed by "          options:"
+    #    and then "            paths:" in that block.
+    for line in lines:
+        if line.startswith("        python:"):
+            in_python = True
+            in_options = False
+            continue
+        if in_python and line.startswith("          options:"):
+            in_options = True
+            continue
+        if in_options and line.startswith("            paths:"):
+            needs_migration = True
+            break
+        # If indentation drops back below python-level, stop looking in this block
+        if in_python and not line.startswith("        ") and not line.isspace():
+            in_python = False
+            in_options = False
+
+    if not needs_migration:
+        return
+
+    # 2) Perform the line-based rewrite:
+    new_lines: list[str] = []
+    inserted_paths = False
+
+    for line in lines:
+        # When we hit the "        python:" line, insert new "          paths:" directly under it
+        if line.startswith("        python:") and not inserted_paths:
+            new_lines.append(line)
+            new_lines.append('          paths: ["src"]\n')
+            inserted_paths = True
+            continue
+
+        # After inserting, drop the old "            paths:" line
+        if inserted_paths and line.startswith("            paths:"):
+            continue
+
+        new_lines.append(line)
+
+    file_path.write_text("".join(new_lines), encoding="utf-8")
+
+
 def apply_patch(patch_content: str) -> None:
     """Apply a patch using the patch utility."""
     subprocess.run(["patch", "-p1"], input=patch_content.encode(), check=True)

cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml

@@ -103,8 +103,8 @@ plugins:
       default_handler: python
       handlers:
         python:
+          paths: ["{{cookiecutter | src_path}}"]
           options:
-            paths: ["{{cookiecutter | src_path}}"]
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false

mkdocs.yml

@@ -101,8 +101,8 @@ plugins:
       default_handler: python
       handlers:
         python:
+          paths: ["src"]
           options:
-            paths: ["src"]
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml

@@ -103,8 +103,8 @@ plugins:
       default_handler: python
       handlers:
         python:
+          paths: ["src"]
           options:
-            paths: ["src"]
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false

tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml

@@ -103,8 +103,8 @@ plugins:
       default_handler: python
       handlers:
         python:
+          paths: ["py"]
           options:
-            paths: ["py"]
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false

tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml

@@ -103,8 +103,8 @@ plugins:
       default_handler: python
       handlers:
         python:
+          paths: ["src"]
           options:
-            paths: ["src"]
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false

tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/mkdocs.yml

@@ -103,8 +103,8 @@ plugins:
       default_handler: python
       handlers:
         python:
+          paths: ["src"]
           options:
-            paths: ["src"]
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false

tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/mkdocs.yml

@@ -103,8 +103,8 @@ plugins:
       default_handler: python
       handlers:
         python:
+          paths: ["src"]
           options:
-            paths: ["src"]
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false