Repository navigation
docs: bare 'Type' in TraceFlow._foutio's autodoc comment is ambiguous across five classes, adding a Sphinx cross-reference warning #709
Description
The Sphinx docs build gains a warning when TraceFlow._foutio is rendered, because its autodoc comment
names a bare Type:
pcapkit/foundation/traceflow/traceflow.py:406: #: Type[Dumper]: Dumper class.
Napoleon resolves that Type against every class of that name in the project, and there are five, so it
emits:
WARNING: more than one target found for cross-reference 'Type'
The same warning already fires 4× on main at base, from other bare Type references; this is a
fifth instance that becomes visible as soon as _foutio carries a directive.
How it surfaced
PR #694 adds an autoattribute for _foutio under the owner's contract-versus-recipe rule (a class
private attribute carrying subclass state is contract and stays documented). The docs build on that
branch goes 55 → 56 warnings, exit 0 both sides, the one new warning being this. make docs runs
sphinx-build -b html without -W, so it does not fail the build — the check is the warning diff.
Why #694 correctly did not fix it
The fix is in pcapkit/, not in docs/, and #694 is a docs-only change that touches no library file.
Its author flagged it rather than either editing outside its ownership or dropping the directive — and
dropping the directive would hide contract to keep a warning count flat, which is the wrong trade.
Suggested fix
Qualify the reference so it resolves uniquely — :class:typing.Type`` or the fully-qualified dumper
type, matching whatever the surrounding #: comments in that file already do for unambiguous names.
Worth sweeping the other four pre-existing bare-`Type` sites in the same change, since they are the same
defect and the count only means something once they are all resolved.
Activity
JarryShaw commentedon Sep 23, 2026
Reopening the scope: this issue's original claim was right, and a "correction" I posted against it was wrong
PR #712 fixes the two bare
Type[Dumper]references inpcapkit/foundation/traceflow/traceflow.py(:146and:406). Its description originally asserted that this issue overstated the problem — that there were "onlytwo source sites" and that the four pre-existing
more than one target found for cross-reference 'Type'warnings were those two rendered at the base class plus subclasses.
That assertion was wrong and has been retracted. A cross-review built the docs on pristine
main(
e86d6b4f3) and traced all four warnings to hand-written:type:fields in three other files:docs/source/pcapkit/foundation/engines/engine.rst:40:type: dict[str, ModuleDescriptor[EngineBase] | Type[EngineBase]]docs/source/pcapkit/foundation/reassembly/reassembly.rst:33:type: Type[Protocol]docs/source/pcapkit/foundation/reassembly/reassembly.rst:43:type: dict[str, ModuleDescriptor[ReassemblyBase] | Type[ReassemblyBase]]docs/source/pcapkit/foundation/traceflow/traceflow.rst:40:type: dict[str, ModuleDescriptor[TraceFlowBase] | Type[TraceFlowBase]]Verified independently by grep. Building with #712's fix applied leaves those four byte-for-byte unchanged.
Where the bad inference came from: the check was
grep -rn '#:.*Type\[' pcapkit/ --include='*.py', whichsearches autodoc comments in the Python tree. The four warnings originate in
docs/source/**/*.rst, so thatgrep could not have found them and returning 2 said nothing about the warning count. Counting warnings requires
reading the build output, which is what the issue asked for in the first place.
What remains open here
#712 is
Part ofthis issue rather than closing it. Still to do:.rst:type:fields above.pcapkit/uses~typing.Type[...]in eight files; butdocs/source/pcapkit/foundation/traceflow/traceflow.rst:30already uses the fully qualifiedtyping.Type[pcapkit.protocols.protocol.ProtocolBase]. The.rsttree has its own convention, and whicheveris picked should be applied consistently rather than mixing them.
Blocked for now:
docs/is owned by open PR #694, so touching these files would collide with it. Thefollow-up should land after #694 merges.
One thing worth recording because it raises the stakes: the same cross-review found that before the fix Sphinx
does not merely warn, it silently links
Typeto the wrong class —pcapkit.const.l2tp.type.Type, an L2TPenum defined at
pcapkit/const/l2tp/type.py:18— rather than dropping the link. So each of these four sites isvery likely rendering a wrong hyperlink in the published docs today, not just a build warning.
fix(traceflow): qualify the bare `Type[Dumper]` autodoc references (#709
docs(changelog): the 1.5.0 entry for #709, whose code partly ships in #…
docs(changelog): fix eight factual errors a cross-review found in the…
fix(traceflow): qualify the bare `Type[Dumper]` autodoc references (#709
fix(docs): qualify the ambiguous Type refs in the foundation rst tree (…
docs(changelog): fix eight defects a second cross-review found in the…
docs(changelog): delete two more wrong claims instead of re-fixing them
fix(docs): stop AppType shadowing six builtins in cross-references
docs(changelog): fix the #709 entry's false causal claim and #684's s…
docs(changelog): fix #678 entry's stale present-tense claim about #685
docs(changelog): fix the #651 entry's stale HIP claims and the html-w…
4 remaining items
docs(changelog): fix eight defects a second cross-review found in the…
docs(changelog): delete two more wrong claims instead of re-fixing them
docs(changelog): fix the #709 entry's false causal claim and #684's s…
docs(changelog): the 1.5.0 entry for #709, whose code partly ships in #…
docs(changelog): fix eight factual errors a cross-review found in the…
docs(changelog): fix eight defects a second cross-review found in the…
docs(changelog): delete two more wrong claims instead of re-fixing them
docs(changelog): fix the #709 entry's false causal claim and #684's s…
docs(changelog): the 1.5.0 entry for #709, whose code partly ships in #…
docs(changelog): fix eight factual errors a cross-review found in the…
docs(changelog): fix eight defects a second cross-review found in the…
docs(changelog): delete two more wrong claims instead of re-fixing them
docs(changelog): fix the #709 entry's false causal claim and #684's s…