Fix mkdocsstrings config (#412)

- **Updated the deprecated `import` config key to `inventories`**
- **Fix wrongly located `paths` key in mkdocs.yml**

Author: llucax

RELEASE_NOTES.md

@@ -27,11 +27,12 @@ But you might still need to adapt your code:
 ### Cookiecutter template
 
 - New warning ignores for protobuf gencode versions in pytest.
+- mkdocstrings: Updated the deprecated `import` config key to `inventories` in `mkdocs.yml`.
 
 ## Bug Fixes
 
 <!-- Here goes notable bug fixes that are worth a special mention or explanation -->
 
 ### Cookiecutter template
 
-<!-- Here bug fixes for cookiecutter specifically -->
+- mkdocstrings: Move `paths` key to the right section in `mkdocs.yml`.

cookiecutter/migrate.py

@@ -34,6 +34,16 @@ def main() -> None:
     # Add a separation line like this one after each migration step.
     print("=" * 72)
     migrate_filterwarnings(Path("pyproject.toml"))
+    print(
+        "Renaming the deprecated mkdocstrings `import` to `inventories` in `mkdocs.yml`..."
+    )
+    print("=" * 72)
+    replace_file_contents_atomically(
+        "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)
@@ -152,6 +162,65 @@ def migrate_filterwarnings(path: Path) -> None:
     )
 
 
+def migrate_mkdocs_yaml(file_path: Path) -> None:
+    """Migrate the mkdocs.yml file to fix the `paths` key location."""
+    if not file_path.is_file():
+        manual_step(f"File {file_path} does not exist, skipping automatic migration.")
+        return
+
+    python_section = "        python:"
+    options_section = "          options:"
+    bad_paths_config = "            paths:"
+
+    lines = file_path.read_text(encoding="utf-8").splitlines(keepends=True)
+    needs_migration = False
+    paths = ""
+    in_python = False
+    in_options = False
+
+    # 1) Detect whether there's a python_section followed by options_section
+    #    and then bad_paths_config in that block.
+    for line in lines:
+        if line.startswith(python_section):
+            in_python = True
+            in_options = False
+            continue
+        if in_python and line.startswith(options_section):
+            in_options = True
+            continue
+        if in_options and line.startswith(bad_paths_config):
+            needs_migration = True
+            paths = line[len(bad_paths_config) :].strip()
+            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_section line, insert new paths config directly under it
+        if line.startswith(python_section) and not inserted_paths:
+            new_lines.append(line)
+            new_lines.append(f"          paths: {paths}\n")
+            inserted_paths = True
+            continue
+
+        # After inserting, drop the old "            paths:" line
+        if inserted_paths and line.startswith(bad_paths_config):
+            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
@@ -116,7 +116,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
-          import:
+          inventories:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv

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
@@ -114,7 +114,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
-          import:
+          inventories:
             - https://cookiecutter.readthedocs.io/en/stable/objects.inv
             - https://docs.python.org/3/objects.inv
             - https://mkdocstrings.github.io/objects.inv

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
@@ -116,7 +116,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
-          import:
+          inventories:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv

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
@@ -116,7 +116,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
-          import:
+          inventories:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv

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
@@ -116,7 +116,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
-          import:
+          inventories:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv

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
@@ -116,7 +116,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
-          import:
+          inventories:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv

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
@@ -116,7 +116,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
-          import:
+          inventories:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv