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.

[JarryShaw]

I'm wondering for those unresolvable mod/meth directives, can we actually use |name|_ with

.. replace:: |name| ``name``  <- reST literal
.. _name: <link to project>

instead?

[JarryShaw]

Yes. esp.py already does this for |cryptography|_. My suggestion is to define each package's substitution and target once, in rst_epilog in conf.py, and use |pyshark|_ and similar for package- and module-level names. Member-level names such as dpkt.dpkt.Packet.data would then all link to the same project homepage, so I'd keep those as literals. conf.py belongs to #1929, and both PRs touch these lines, so I'll do this as a follow-up once #1928 and #1929 merge. That keeps this PR's verdict and rebase simple. I'll also check whether #1929's type-hint formatter can emit the same substitutions under the pinned build, which must stay at 0 warnings.

[JarryShaw]

Sounds good. In that case, we have several other similar existing practices that can be added to the rst_epilog as well.

Now for the PR, resolve conflicts.

[JarryShaw]

Will do. I'm rebasing this onto main now and resolving the esp.py conflict with #1907's edits.

The two engine comment lines in pcap_ct.py and pypcap.py take both changes: the pcap literal from here and the cf. spelling from #1911. #1911 drops its own edit to those two lines, so the two PRs no longer overlap and can merge in either order. #1936 now also covers moving the repo's other per-file substitutions into rst_epilog.

[JarryShaw]

GOOD TO GO at 44c524337, rebased onto 8f213fea7. A Sonnet re-review compared the PR's diff before and after the rebase, file by file. Every difference comes from one of the conflict resolutions: cf. plus the pcap literal on the engine lines, and #1907's see with the cryptography literal on the esp.py cache comment. #1907's Returns: rewrite needs no demotion: cryptography.exceptions.InvalidTag (py:class) and cryptography.hazmat.primitives.ciphers (py:module) are both in cryptography's inventory. conf.py emits roles only for packages listed in intersphinx_mapping, so the test now scans it too. All 30 changed .py files are AST-identical, and merge-tree against main is clean.