docs: retarget or demote cross-references that cannot resolve (#1919, #1920)

[JarryShaw]

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change

• Added a changelog entry — N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

• docs — documentation only

Some roles can never resolve, so they render as unlinked chips. Following #934:

• Roles into aenum, pcap, pcapfile and pyshark become literals.
• So do dpkt, scapy and cryptography targets that their inventories lack, and names with no entry (warnings.filters, abc.ABCMeta.__new__, _declared_keywords, OptionEnumField.post_process).
• Targets that do exist are retargeted: warnings.catch_warnings as a class, dictdumper.dumper.Dumper and collections.abc.Mapping.
• compat.final and EnumMeta.registry are now documented.

Only docstrings, comments and .rst change, and every changed .py is AST-identical. A new test rejects inventory-less roles across docs/ and pcapkit/, and fails on main. The pinned docs build has 0 warnings and no new chips.

Still open: the conf.py formatter and the aenum roles in pcapkit/vendor/ and pcapkit/const/ (#1920). #1911 touches the same c.f. comment line in engines/pcap_ct.py and pypcap.py, so whichever PR merges second needs a two-line rebase.

Closes #1919
Refs #1920

[JarryShaw]

NEEDS CHANGES at a5e5cc895. The substance holds. A Sonnet cross-review checked every demoted target against the downloaded Python, dictdumper, dpkt, scapy and cryptography inventories, and none of them resolves. The retargets exist. compat.final's versionchanged:: 1.5.0 matches v1.4.1.post2 (< (3, 8)) against main (< (3, 11)). All 27 changed .py are AST-identical, and the new test fails on main. One thing left: the new test's prose carries timed context. Its module docstring says "the form it used to take" and "gained an entry rather than losing the role". DocumentedEntryTests says "gained an entry", and line 170 says "stays gone". Restate each as what the test checks.

[JarryShaw]

GOOD TO GO at e0897af5f. The test's prose no longer carries timed context, and the renamed test_no_dead_target_appears passes. pcapkit.vendor.__main__.run has no autodoc entry, because vendor/index.rst documents only the module, so a literal next to :mod: is right. The narrowed exclusion covers exactly the two vendor templates that still carry aenum roles, and those are the files #1927 edits. default.py is AST-identical to main.

[JarryShaw]

Merge-order note. A combined-tree merge of every open PR on main (87e1fb5aa) shows that this PR conflicts with #1907 in protocols/internet/esp.py, and with #1911 in engines/pcap_ct.py and pypcap.py. In each spot both PRs edit the same c.f. comment line or :mod: role line. These conflicts are inherent, so the simplest order is to merge #1907 and #1911 first; I will then rebase this PR and keep both changes. The verdict above still stands for the content.

[github-actions]

Coverage: 90.07% (unit tier, Python 3.15, e0897af5f, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	2	20	2	96.77%
pcapkit/const	19595	881	2618	867	92.11%
pcapkit/corekit	2504	70	792	36	96.54%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2916	164	1016	34	93.59%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17411	224	4580	189	98.10%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	522	2	158	4	99.12%
pcapkit/vendor	4431	2341	1018	156	43.64%

Per-file detail: the coverage-html artifact of this run.