Add support for mkdocstrings-python v2 (#481)

Fixes #482, #483, #357.

Author: llucax

RELEASE_NOTES.md

@@ -22,7 +22,7 @@ But you might still need to adapt your code:
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+* `mkdocsstrings-python` v2 is now supported.
 
 ### Cookiecutter template
 
@@ -31,6 +31,8 @@ But you might still need to adapt your code:
 - Dependencies have been updated.
 - Added Dependabot auto-merge workflow using `frequenz-floss/dependabot-auto-approve` action.
 - Migration script now creates auto-merge workflow and disables CODEOWNERS review requirement via GitHub API.
+- The `import` key in `mkdocs.yml` under `mkdocstrings` has to be renamed to `inventories`.
+- The `paths` key in `mkdocs.yml` under `mkdocstrings` has to be moved from the `options` key to the `python` key.
 
 ## Bug Fixes
 

cookiecutter/migrate.py

@@ -39,10 +39,31 @@ def main() -> None:
     print("Disabling CODEOWNERS review requirement in GitHub ruleset...")
     disable_codeowners_review_requirement()
     print("=" * 72)
+    print("Updating the mkdocs.yml for mkdocstrings-python v2 compatibility...")
+    update_mkdocs_yml_mkdocstrings_python_v2()
+    print("=" * 72)
     print("Migration script finished. Remember to follow any manual instructions.")
     print("=" * 72)
 
 
+def update_mkdocs_yml_mkdocstrings_python_v2() -> None:
+    """Rename 'inventories' imports to 'inventory'."""
+    replace_file_contents_atomically(
+        filepath=Path("mkdocs.yml"),
+        old="          import:",
+        new="          inventories:",
+    )
+    replace_file_contents_atomically(
+        filepath=Path("mkdocs.yml"),
+        old="""\
+          options:
+            paths: ["src"]""",
+        new="""\
+          paths: ["src"]
+          options:""",
+    )
+
+
 def create_dependabot_auto_merge_workflow() -> None:
     """Create the Dependabot auto-merge workflow file."""
     workflow_dir = Path(".github") / "workflows"

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

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

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

@@ -99,8 +99,8 @@ dev-mkdocs = [
   "mkdocs-literate-nav == 0.6.2",
   "mkdocs-macros-plugin == 1.3.9",
   "mkdocs-material == 9.6.18",
-  "mkdocstrings[python] == 0.30.0",
-  "mkdocstrings-python == 1.17.0",
+  "mkdocstrings[python] == 1.0.0",
+  "mkdocstrings-python == 2.0.1",
   "frequenz-repo-config[{{cookiecutter.type}}] == 0.13.1",
 ]
 dev-mypy = [

pyproject.toml

@@ -41,7 +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",
+  "mkdocstrings-python >= 1.14.6, < 3",
 ]
 dynamic = ["version"]
 
@@ -83,8 +83,8 @@ dev-mkdocs = [
   "mkdocs-literate-nav == 0.6.2",
   "mkdocs-macros-plugin == 1.4.0",
   "mkdocs-material == 9.6.21",
-  "mkdocstrings[python] == 0.30.1",
-  "mkdocstrings-python == 1.18.2",
+  "mkdocstrings[python] == 1.0.0",
+  "mkdocstrings-python == 2.0.1",
 ]
 dev-mypy = [
   "mypy == 1.18.2",

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

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

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

@@ -58,8 +58,8 @@ dev-mkdocs = [
   "mkdocs-literate-nav == 0.6.2",
   "mkdocs-macros-plugin == 1.3.9",
   "mkdocs-material == 9.6.18",
-  "mkdocstrings[python] == 0.30.0",
-  "mkdocstrings-python == 1.17.0",
+  "mkdocstrings[python] == 1.0.0",
+  "mkdocstrings-python == 2.0.1",
   "frequenz-repo-config[actor] == 0.13.1",
 ]
 dev-mypy = [

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

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

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

@@ -69,8 +69,8 @@ dev-mkdocs = [
   "mkdocs-literate-nav == 0.6.2",
   "mkdocs-macros-plugin == 1.3.9",
   "mkdocs-material == 9.6.18",
-  "mkdocstrings[python] == 0.30.0",
-  "mkdocstrings-python == 1.17.0",
+  "mkdocstrings[python] == 1.0.0",
+  "mkdocstrings-python == 2.0.1",
   "frequenz-repo-config[api] == 0.13.1",
 ]
 dev-mypy = [

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

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