Render undocumented TypeVars as text#14504
Conversation
gaborbernat
force-pushed
the
fix-restify-typevar
branch
3 times, most recently
from
7c32d9d to
fa3d857
Compare
gaborbernat
force-pushed
the
fix-restify-typevar
branch
from
fa3d857 to
bcb6c31
Compare
|
Please update the PR description in accordance with the AI policy: https://www.sphinx-doc.org/en/master/internals/ai-policy.html |
|
@jdillard Updated the description per the AI policy, with a disclosure line added. |
picnixz
left a comment
picnixz
left a comment
There was a problem hiding this comment.
Documenting TypeVars is, AFAIR, possible with #: or bu explicitly adding an entry for it IIRC. I may be wrong but if this is the case, you must also add tests for autodoc.
I do not think that list[TypeVar(T)] is an acceptable rendering however.
picnixz
left a comment
picnixz
left a comment
There was a problem hiding this comment.
Please do not request a review if there is no new code.
gaborbernat
force-pushed
the
fix-restify-typevar
branch
from
bcb6c31 to
dfa0e4e
Compare
|
Reworked per your feedback: dropped the |
gaborbernat
force-pushed
the
fix-restify-typevar
branch
from
dfa0e4e to
80790f0
Compare
picnixz
left a comment
picnixz
left a comment
There was a problem hiding this comment.
Please add E2E tests with autodoc as well (you would likely need toc reate some testdata in testroot)
restify() links a TypeVar by its qualified name. A private or otherwise undocumented type variable has no documentable target, so a nitpicky or -W build of a class deriving from Generic[_T] failed with a dangling py:obj reference. Add a missing-reference handler that renders the reference as text when its target resolves to a TypeVar or ParamSpec, leaving documented ones and intersphinx links untouched. Fixes sphinx-doc#14502.
gaborbernat
force-pushed
the
fix-restify-typevar
branch
from
80790f0 to
259228d
Compare
|
We don't use conventional commit titles in our PRs (and especially not emojis) |
picnixz
left a comment
picnixz
left a comment
There was a problem hiding this comment.
Please don't force push, it's impossible to make incremental reviews.
Cover documented and undocumented type variables across bases, methods, and a module-level function, plus covariant, bound, constrained, and ParamSpec cases. A documented one links; an undocumented one renders as text. Follows up on review feedback for sphinx-doc#14504.
3 participants
Documenting a class that derives from
Generic[_T]withshow-inheritancefailed anitpickyor-Wbuild whenever_Tis private or otherwise undocumented, reportingpy:obj reference target not found.restify()links a type variable by its qualified name, and a name with no documentable target leaves a dangling cross-reference, as reported in #14502.A new
missing-referencehandler resolves that reference to plain text once it sees the target is aTypeVarorParamSpec. A documented type variable, or one reachable through intersphinx, still links as before, and the rendering stays the bare name rather than an expandedTypeVar(...)form.Generic base classes that use an undocumented type variable no longer warn, and documented references keep their links.
AI disclosure: I drafted this description with Claude Code (Anthropic), then reviewed and tested it. The change is mine and I take responsibility for it.