docs: Update mkdocstrings-python to 2.x and fix cross-reference paths #3706
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
The `returns_named_value` and `returns_multiple_items` options are only valid for the Google docstring parser. Passing them to Sphinx/Numpy parsers now triggers a DeprecationWarning in griffe. Also fixed cross-reference paths in docstrings to use the full module path (e.g. `pydantic_ai.agent.Agent` instead of `pydantic_ai.Agent`). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Collaborator
| @dsfaccini docs CI is failing! |
Collaborator Author
| Ik!! mkdocs seems to depend on some pinned private package, this is just a sidequest, if I can figure it out with Samuel/whoever pinned the insiders we can merge otherwise it's fine |
Collaborator Author
| So, we we're using an "insiders" version of some mkdocs packages because Pydantic was a sponsor and they had nice features. But they made the features public (very recently lol)
So I'm changing the @DouweM I'm not allowed to modify the CI file but you can remove these lines. And the now dummy lines in the |
dsfaccini commented Dec 12, 2025
All mkdocs-material and mkdocstrings-python insiders features have been released to the public as of November 2025. - mkdocs-material v9.7.0: All insiders features now public - mkdocstrings-python v2.0.0: All insiders features now public Changes: - Remove mkdocs.insiders.yml (merge into mkdocs.yml) - Update mkdocs-material to >=9.7.0 (for material.extensions.preview) - Update Makefile docs-insiders to be a no-op (calls docs) - Simplify cf-pages-build to use public packages Sources: - https://squidfunk.github.io/mkdocs-material/blog/2025/11/11/insiders-now-free-for-everyone/ - https://mkdocstrings.github.io/python/changelog/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
dsfaccini force-pushed the update-mkdocstrings-fix-crossrefs branch from fd53940 to 3940dae Compare 
Docs Preview
|
Collaborator
| @dsfaccini I've updated ci.yml and Makefile! |
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
Updates mkdocstrings-python from 1.x to 2.x to fix deprecation warnings in docs build.
Changes:
mkdocstrings-python>=1.12.2→>=2.0.0import:→inventories:(required by mkdocstrings 1.0+)pydantic_ai.Agent.*→pydantic_ai.agent.Agent.*pydantic_evals.Dataset/Case.*→pydantic_evals.dataset.*pydantic_ai.Tool.*→pydantic_ai.tools.Tool.*pydantic_ai.RunContext.*→pydantic_ai.tools.RunContext.*pydantic_ai.ui.UIAdapter.*Resolves deprecation warnings from https://github.com/pydantic/pydantic-ai/actions/runs/20134237380/job/57783147568