Conversation
WalkthroughTwo files are updated: the Sphinx version constant is bumped from 8.1.3 to 9.0.4 in a context configuration file, and type annotations in a VCR.py fixtures module are refactored to replace Pydantic's JsonValue with standard Python typing constructs. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Possibly related PRs
Pre-merge checks❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
extensions/context.py(1 hunks)template/copier_template_resources/{% if template_might_want_to_use_vcrpy %}vcrpy_fixtures.py{% endif %}(2 hunks)
🔇 Additional comments (2)
template/copier_template_resources/{% if template_might_want_to_use_vcrpy %}vcrpy_fixtures.py{% endif %} (2)
2-2: Successfully removes pydantic dependency.The addition of
from typing import Anysupports the standard library type annotations, eliminating the need for pydantic'sJsonValue.
45-45: Type annotation is functional but imprecise.The new type
dict[str, str | dict[str, Any]]successfully removes the pydantic dependency. However, it's narrower thanJsonValue, which also includesint,float,bool,None, andlist. VCR response objects can contain these types.Since the PR explicitly states "the fixture's typing is not critical" and this has been tested downstream, the current approach is acceptable for test fixtures where strict typing is less important.
If stricter typing becomes needed later, consider:
dict[str, str | int | float | bool | None | dict[str, Any] | list[Any]]Or simply
dict[str, Any]for maximum flexibility in test fixtures.
| context["pytest_cov_version"] = "7.0.0" | ||
| ####### | ||
| context["sphinx_version"] = "8.1.3" | ||
| context["sphinx_version"] = "9.0.4" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, examine the file to understand context
head -50 extensions/context.py | cat -nRepository: LabAutomationAndScreening/copier-base-template
Length of output: 2654
🌐 Web query:
Sphinx 9.0.4 release official version valid
💡 Result:
Yes — Sphinx 9.0.4 is an official release (released Dec 4, 2025). Evidence: the Sphinx changelog shows "Release 9.0.4 (released Dec 04, 2025)." [1] The PyPI project page lists and provides the signed v9.0.4 packages (uploaded Dec 4, 2025) with provenance metadata. [2]
Sources:
[1] Sphinx changelog — Sphinx 9.0 (changes).
[2] Sphinx on PyPI (sphinx‑9.0.4 files & provenance).
🌐 Web query:
Sphinx 9.0 breaking changes migration guide
💡 Result:
Here are the key breaking changes in Sphinx 9.0 and concise migration steps.
Summary of breaking changes (from the official 9.0 release notes). [1]
- Autodoc rewritten: sphinx.ext.autodoc was substantially rewritten; this can break extensions or code that relied on autodoc internals. A config option autodoc_use_legacy_class_based is provided to restore the pre‑9.0 behavior. [1]
- SphinxComponentRegistry.create_source_parser() signature changed: it no longer accepts an app parameter — it now takes config and env. Update any code/extension that calls this API. [1]
- Non‑decodable bytes in source files now raise an error (previously were replaced by "?" and only warned). Ensure source files are properly encoded (UTF‑8) or pre‑clean inputs. [1]
- Don’t include escaped title content in the search index (search index behavior changed). Review any tooling that depended on the old indexed content. [1]
Recommended migration steps
-
Pin and test
- Pin Sphinx to 9.x in a test branch (pip install "sphinx>=9.0,<10.0") and run your full doc build and CI. Fix issues before rolling to main.
-
Autodoc compatibility
- If builds break due to autodoc/extension interactions, set in conf.py:
autodoc_use_legacy_class_based = True
then update the extensions or code to work with the new autodoc implementation and remove the legacy flag once fixed. [1]
- If builds break due to autodoc/extension interactions, set in conf.py:
-
Update extension/extension calls
- Search your codebase and third‑party extensions for calls to SphinxComponentRegistry.create_source_parser() and change arguments from (app, ...) to (config, env, ...), following the new signature. Test extension APIs. [1]
-
Fix file encodings and sources
- Convert any files with non‑UTF‑8 or non‑decodable bytes to UTF‑8 and remove stray non‑decodable bytes. Treat build warnings about encoding as errors to find offending files. [1]
-
Search/index differences
- If you rely on the old behavior of titles being escaped in the index, re‑test search and update any consumer code or search customization to match the new indexed content. [1]
-
Upgrade third‑party extensions/themes
- Upgrade sphinx plugins, themes, and custom extensions to versions that declare Sphinx 9 support. If an extension uses autodoc internals or Sphinx internals, check its changelog or issue tracker for 9.x fixes.
-
Use CI and automated regressions
- Add a doc build step to CI that runs Sphinx with warnings-as-errors (SPHINXOPTS='-W') to catch regressions early.
If you want, I can:
- scan your conf.py and extensions to find likely incompatible calls (like create_source_parser usage) and give exact edits; or
- produce a short checklist/PR template to upgrade a project to Sphinx 9.0.
Sources
- Sphinx 9.0 release notes / incompatible changes. [1]
- Sphinx release process (versioning & deprecation guidance). [2]
References
[1] Sphinx 9.0 release notes — Sphinx documentation.
[2] Sphinx’s release process — Sphinx documentation.
Ensure downstream projects test documentation builds with Sphinx 9.0.4 to account for breaking changes.
Sphinx 9.0.4 is a valid official release (Dec 4, 2025), but the major version bump introduces breaking changes that downstream projects need to handle. Key changes include:
- Autodoc rewritten (may break custom extensions relying on autodoc internals—use
autodoc_use_legacy_class_based = Trueas a temporary workaround) SphinxComponentRegistry.create_source_parser()API signature changed- Non-decodable bytes in source files now raise errors instead of warnings
- Search index behavior changed for escaped title content
Verify that projects generated from this template have tested their documentation builds with Sphinx 9.0.4 and updated any extensions or themes to Sphinx 9.x-compatible versions.
🤖 Prompt for AI Agents
In extensions/context.py around line 27, the template currently pins
context["sphinx_version"] = "9.0.4" but downstream projects need explicit
guidance and CI/test support for Sphinx 9.x breaking changes; update this area
to (1) keep the pinned version but add a brief comment/instruction that
downstream projects must run documentation builds against Sphinx 9.0.4 in CI,
(2) document the recommended temporary workaround autodoc_use_legacy_class_based
= True for autodoc breakage, (3) add notes to the template README or docs
scaffold to check extensions/themes for Sphinx 9.x compatibility and to handle
changed APIs and stricter byte-decoding, and (4) ensure the project's dev
requirements / docs build job in CI are updated to install/test with
Sphinx==9.0.4 so failures surface early.
1 participant
Why is this change necessary?
Unnecessary type hint imported from pydantic for use in general fixture
How does this change address the issue?
switches to dict[str, Any], since this fixture doesn't matter that much about typing
What side effects does this change have?
N/A
How is this change tested?
Downstream repos
Other
bumped sphinx
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.