Skip to content

docs(conf): resolve the 36 ambiguous cross-references at their source - #1790

Merged
JarryShaw merged 1 commit into
mainfrom
docs/1775-ambiguous-xrefs
Oct 15, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/1775-ambiguous-xrefs

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

Please follow the guide below

What is the purpose of your pull request?

Tick the commit type your subject line carries.

  • fix — corrects a defect
  • feat — adds a feature
  • perf — changes performance, not behaviour
  • refactor — changes neither behaviour nor performance
  • test — tests only
  • docs — documentation only
  • ci — workflows or build tooling
  • release — bumps the version or rolls up a distribution
  • chore — anything else

Summary

The docs build gave 36 "more than one target found" warnings. They are fixed at their source; the build now has 0, with no new warnings of any kind (clean -E builds, compared by page, kind and reference).

  • dict, type, set (25): Sphinx's fuzzy suffix search matched registry members such as TCP.dict. A doctree-read hook in conf.py removes the fuzzy flag from implicit references to builtin names; explicit roles keep their search.
  • http, Echo (4): napoleon split enum-member docstrings at a URL's colon into a fake Type field, on 51 members. A save/restore pair around napoleon (priorities 400/600) undoes that.
  • TypeVars _AT, _IT, _BT, _DT (7): 44 hand-written directives repeated their module in the name. They take the bare name now, and links reach the right module's TypeVar.
  • Tests: tests/project/test_docs_ambiguous_xrefs_1775_unit.py pins the hooks with real Sphinx nodes, the event wiring, and the directive names. The Sphinx-dependent tests skip in CI behind a declared HAS_SPHINX gate. Each hook, wiring line and priority fails a test when mutated.
  • Follow-up: the convention "a hand-written directive takes the bare name under its .. module::" belongs in documentation.rst, which chore: drop stale build leftovers and move the examples' READMEs to Markdown (#1773) #1780 is editing.

Closes #1775

- conf.py: resolve_builtins_exactly drops the fuzzy-search flag from an
  implicit reference to a builtin name, so `dict`, `type` and `set` in a
  type reach the Python docs instead of the registry members TCP.dict,
  Command.type and TCP.set (25 warnings).
- conf.py: save/restore_enum_member_docstring undo napoleon's inline
  `type: description` split on enum members, which turned a URL's colon
  into a bogus Type field on 51 registry members (the 4 `http`/`Echo`
  warnings).
- docs: 44 `.. data::`/`.. function::` directives repeated their module
  in the name and registered as `<module>.<module>.<name>`; they take the
  bare name now, with `:module:` where it differs. Two `:type:` options
  qualify `_AT` (the 7 TypeVar warnings).
- tests: pin the hooks against real Sphinx nodes and napoleon, and the
  events and priorities setup() connects them at, behind a declared
  HAS_SPHINX gate, and the directive names textually.

Docs build: 0 ambiguity warnings (was 36), no new warnings.

Closes #1775
@JarryShaw JarryShaw added the docs Pull requests that change documentation only (docs: subject prefix) label Oct 15, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

Verdict: GOOD TO GO at 4041fe34a. A Sonnet cross-review (author: Opus) ran its own clean builds: 36 ambiguity warnings became 0, and the other 18 warnings are unchanged. It diffed all 198 pages' links: 25 builtin links now reach the Python docs, the TypeVar links reach the right module, and nothing else changed. A follow-up added tests for setup()'s event wiring; a Sonnet check confirmed each of eight mutations fails a test.

@JarryShaw JarryShaw added the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 15, 2026
@JarryShaw JarryShaw moved this to In review in PyPCAPKit Oct 15, 2026
@JarryShaw
JarryShaw merged commit ae82e6d into main Oct 15, 2026
53 checks passed
@JarryShaw
JarryShaw deleted the docs/1775-ambiguous-xrefs branch October 15, 2026 22:00
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Oct 15, 2026
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 15, 2026
JarryShaw added a commit that referenced this pull request Oct 15, 2026
…1803)

Entries:
- add #1791 (breaking: pack() leaves its instance unchanged), #1778
  (Protocol in protocol.__all__), #1781 (PortEnumField miss with a
  nameless proto), #1779 (vendor.ipx _path), #1780 (examples READMEs to
  Markdown, build leftovers) and #1790 (36 ambiguous cross-references)
- fold #1776 into the RPL 0x23 entry and #1381 into the dump-schema one

Accuracy:
- the benchmark and legacy_smoke READMEs are README.md since #1780
- EngineBase stays out of __all__, as #1016 settled
- the #575 peek calls get() only once the value resolves
- the #647 and #764 entries point at #775/#860, under which nothing mints
- the #861 entry names #869 and #874 for the EnumRegistry move

Figures:
- preamble: 685 citations, #340 to #1791
- process.rst pin: 298 entries; CHANGELOG.md regenerated

Refs #1103
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

docs: 36 ambiguous cross-reference warnings from registry members named dict, set and type

1 participant