docs: fix invalid :pyclass: Sphinx role in session docstrings#3367
Closed
Quratulain-bilal wants to merge 3 commits into
Closed
docs: fix invalid :pyclass: Sphinx role in session docstrings#3367Quratulain-bilal wants to merge 3 commits into
Quratulain-bilal wants to merge 3 commits into
Conversation
`:pyclass:` is not a valid Sphinx / mkdocstrings cross-reference role — the canonical form is `:class:` (or the fully-qualified `:py:class:`). Four session backend classes used the typo, which was propagated by copy-paste across PRs from different authors. The sibling `extensions/memory/__init__.py` already uses `:class:` for the same target, so this aligns the four backends with the existing convention. No behavior change; affects rendered docs only.
Member
|
Thanks for suggesting this change. This project's documentation site does not use sphinx, so your changes don't still work well. I've fixed this issue by #3370 |
Quratulain-bilal
deleted the
docs/fix-pyclass-sphinx-role-in-session-docstrings
branch
Quratulain-bilal
restored the
docs/fix-pyclass-sphinx-role-in-session-docstrings
branch
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
Four session backend class docstrings use
:pyclass:, which is not a validSphinx / mkdocstrings cross-reference role. The canonical form is
:class:(short) or
:py:class:(fully qualified). The siblingsrc/agents/extensions/memory/__init__.py:5already uses:class:for thesame target, so this aligns the four backends with the existing convention.
Files changed
src/agents/extensions/memory/sqlalchemy_session.pysrc/agents/extensions/memory/redis_session.pysrc/agents/extensions/memory/dapr_session.pysrc/agents/extensions/memory/mongodb_session.pyWhy
:pyclass:is a copy-paste typo that propagated across PRs from fourdifferent authors (different dates, per
git blame) — each new sessionbackend was written by copying an existing one.
grepconfirms zero usesof
:py:class:anywhere insrc/, and 1 existing use of:class:for theexact same target in the sibling
__init__.py. So short:class:is theestablished convention.
Risk
None — docstring rendering only, no behavior change.
ruff checkandruff format --checkpass.Test plan
uv run ruff check src/agents/extensions/memory/— cleanuv run ruff format --check src/agents/extensions/memory/— cleangrep ":pyclass:" src/that no other occurrences remain__init__.pyalready uses:class:for the same target