Repository navigation
[Docs] Fix accidental cross-references in docstrings - #65157
Merged
Merged
Conversation
Docstrings render as Markdown, so array shapes like `[block][2][16]` were parsed as reference links and produced mkdocs_autorefs warnings. Wrap them in code spans and add a pre-commit hook that flags reference links in rendered docstrings whose target is not a fully qualified Python path. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Rename the hook and add a rule that rewrites ``code`` as `code` in docstrings, skipping fenced, indented and doctest blocks and spans that contain a backtick. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Mechanical rewrite by `python tools/pre_commit/check_docstring_style.py`. Only docstrings change; ASTs are otherwise identical and line counts are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
hmellor
requested review from
AndreasKaratzas,
MatthewBonanni,
TheEpicDolphin,
WoosukKwon,
ZJY0516,
aoshen02,
bigPYJ1151,
gau-nernst,
njhill,
shen-shanshan,
tdoublep,
tomeras91,
vadiklyutiy,
xuechendi,
yewentao256 and
zyongye
as code owners
November 2, 2026 12:49
hmellor
requested review from
BoyuanFeng,
Isotr0py,
ProExpertProg,
bnellnm,
jeejeelee,
wzhao18 and
zou3519
as code owners
November 2, 2026 12:49
hmellor
changed the title
mergify
Bot
added
cohere
Moved to a separate PR to keep this one a small docs fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
6 tasks done
Point each at the offending line rather than the docstring start. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Keep this PR to the docs fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
DarkLight1337
approved these changes
Nov 2, 2026
6 tasks done
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
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.
Overview
Docstrings render as Markdown, so array shapes like
[block][2][16]were parsed as reference links and producedmkdocs_autorefs"Could not find cross-reference target" warnings. This wraps them in code spans. A pre-commit hook to stop them coming back is in #65158.Claims
mkdocs_autorefswarnings (kimi_k3,muse_spark) plus 3 more of the same kind (_custom_ops.py,minimax_m3).Validation
The hook from #65158 reports 14 hits on the
upstream/mainversions of these files (all 11 reported warnings + 3) and 0 on everyvllm/**/*.pyin this branch.pre-commit runpasses.No open PR addresses this (searched "autorefs", "mkdocs_autorefs", "cross-reference docstring"). I didn't run a local mkdocs build; the RTD preview build on this PR covers that.
Pull Request Checklist
I used vLLM's
/pr-checklistskill. (Mandatory for agents, optional for humans).AI assistance was used during the creation of this PR.
Design Fit: Minimizes impact on core components, reuses existing functionality, and justifies added complexity.
Testing and Validation: Validates the change and ensures any added tests are meaningful and reliable, with CI coverage or documented CI resource constraints and validation performed outside CI.
Code Quality and Style: Keeps code and comments clear and concise, and updates relevant documentation and examples.
Pull Request Contents: Includes a brief summary and relevant links, supports claims with evidence, explains root causes and implementation trade-offs, and follows the contributing guide.
🤖 Generated with Claude Code