diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 6fbb0c5c..d4851bae 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -27,6 +27,7 @@ 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 @@ -34,4 +35,4 @@ But you might still need to adapt your code: ### Cookiecutter template - +- mkdocstrings: Move `paths` key to the right section in `mkdocs.yml`. diff --git a/cookiecutter/migrate.py b/cookiecutter/migrate.py index e4b3eae1..e9f3943f 100644 --- a/cookiecutter/migrate.py +++ b/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) diff --git a/cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml b/cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml index 2bb2105b..476d4c34 100644 --- a/cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index f9a0397a..e6a88ec3 100644 --- a/mkdocs.yml +++ b/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 diff --git a/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml index 95d90c78..2a28152f 100644 --- a/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml +++ b/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 diff --git a/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml index 4c4196ab..337aaf66 100644 --- a/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml +++ b/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 diff --git a/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml index ea2d972f..78209bdf 100644 --- a/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml +++ b/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 diff --git a/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/mkdocs.yml index 1d4c8edf..721c8280 100644 --- a/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/mkdocs.yml +++ b/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 diff --git a/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/mkdocs.yml index ade2d5ab..946df0b4 100644 --- a/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/mkdocs.yml +++ b/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