docs(vendor,const): convert bare citations to the issue role in generators and generated files

[JarryShaw]

Please follow the guide below

• Searched for similar pull requests
• Followed the coding style
• make test passes, and a test case covers the change — tests/vendor, tests/const and the docstring contract are green; two existing assertions updated, see below
• 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

What is the purpose of your pull request?

• docs — documentation only

---

Description of your pull request and other information

Last tranche of #989, after #1000, #1002, #1003 and #1004. Covers pcapkit/vendor/ and pcapkit/const/.

This one could not be done in the generated files alone. pcapkit/const/ docstrings are emitted by the pcapkit/vendor/ generators — the same prose appears on both sides — so editing a const file would be reverted at the next regeneration. The conversion is made in the generator's LINE templates and mirrored into the checked-in generated file. The crawlers were deliberately not run: they fetch live IANA and Wikipedia registries, #518 records 403s and a dead IETF URL against them, and a regeneration would pull unrelated registry churn into a citation-only diff.

99 roles across 21 distinct numbers, every one an issue: 50 in ordinary string tokens, 37 inside the LINE f-string templates, 12 in #: doc-comments.

27 bare citations deliberately remain, and both groups are right to:

• 25 inside the templates emit plain # comments in the generated const files, which the ruling on docs: bare #NNN citations do not resolve in Sphinx — add an extlinks role instead of auto-linking #989 keeps bare. Every one sits on a template line starting with # — checked individually, 25 of 25.
• 2 are ImportError messages (vendor/ngap/procedure_code.py:148, vendor/ngap/protocol_ie.py:120). A role there would print as raw markup in a user's traceback, so it stays bare — the same reasoning that excludes the SchemaError f-string in docs(schema): convert bare citations to the issue role in docstrings #1004.

Regeneration is a no-op, evidenced without running a crawler: 37 of the 38 const role sites have a vendor template origin, and for each of ftp/command, http/method and reg/apptype/apptype the ordered list of (issue number, line text) is equal on both sides after unescaping {{/}} — 12, 11 and 14 sites. The one exception, const/ngap/__init__.py:23, is hand-written with different prose from its vendor counterpart and was converted directly. Only the ngap, ipv6 extension-header and ipx-socket modules have byte-for-byte regeneration tests; ftp, http and apptype do not, which is why the text equality is the evidence.

Two existing assertions updated. tests/const/test_const_method_value_lookup_908_unit.py:326,341 asserted the literal 'GitHub issue #908' against the generated source, pinning the citation form this ruling changes. They now accept either form via assertRegex, so a future markup change does not break them again; the companion source in rendered assertion still pins the vendor and const text to each other exactly. The module's own prose is untouched — that belongs to #719's tests/ sweep.

Also checked: 0 roles nested inside **…**, *…* or ``…`` — the defect class found on #1004, which renders as literal markup with no Sphinx warning. Docs build warning sets identical before and after.

[JarryShaw]

GOOD TO GO at f89696fb2 — opus cross-review, a different model from the sonnet agent that authored the diff. No defect. It replaced three of my checks with stronger ones and corrected one of my premises.

• The 25 bare template citations were verified by their output, not by my crude "line starts with #" test. Each has a 1:1 counterpart in the generated const file that tokenize classifies as a plain COMMENT — exactly 25 such sites. And converting the two ImportError strings would have reddened real tests: tests/vendor/test_vendor_ngap_unit.py:169,180 assert '#880' appears in the raised exception text.
• Template/const parity was proven by rendering, not text equality. Each template was called with stub data; the rendered output matches the const file verbatim on every line apart from the substitution regions, with 11/12/14 citation sites per side. 37 + the hand-written const/ngap/__init__.py:23 = 38.
• Byte-level confirmation of "pure markup": collapsing :issue:N`` back to #N makes 18 of 19 files byte-identical to base, the 19th differing only by the two assertion lines. Zero reflow, zero prose edit — and that also proves no URL was converted, since a converted URL could not collapse back.
• Roles do render: +26 /issues/N anchors across the built pages, no literal :issue: surviving outside Pygments source listings.

Correcting my own brief: I told the reviewer that a role nested inside markup spanning a line break was a detection gap worth hunting. docutils resolves roles and **…** spans across line breaks — I reproduced both — so that is not a separate failure mode; the nesting is, and all 99 roles here are single-line. The parser-based scan found 0 raw survivors across 38 blocks.

One trade the body did not state, worth recording: the relaxed assertRegex accepts the bare form too, so it can no longer catch a regression back to #908 in that docstring — which #989 now rules out. Defensible, since tests/corekit/test_sentinel_exports_unit.py:419 already set that precedent, but it is a loosening.

Not ready to merge: main moved under this branch (#1001–#1004 landed), so it is BEHIND and needs updating before CI can be trusted.

[JarryShaw]

Rebased onto 326a0e5ae, new head 913e54cba — the branch was BEHIND after #1001–#1004 landed, and strict mode means a run on the old base does not count.

The GOOD TO GO verdict carries to this head, and that is measured rather than assumed. The rebase is content-identical: git diff e8a60d153...f89696fb2 and git diff 326a0e5ae...913e54cba are byte-for-byte the same patch, md5 29bd56cb92b42a8569cae6e603ee4ad1 both ways, still 19 files at 94+/94−. Rebase was clean, no conflicts — expected, since the four merged tranches touched docs/source/conf.py, foundation/utilities/toolkit/dumpkit, protocols/internet and the rest of protocols/, none of which this branch goes near.

Re-derived against the new base rather than carried over: 99 roles (50 STRING, 37 FSTRING_MIDDLE, 12 #:), 21 distinct numbers, 27 bare citations remaining, collapse-back leaving 18 of 19 files byte-identical with the 19th differing only by the two assertion lines, and 0 nested-markup sites. tests/vendor, tests/const and the docstring contract: 424 passed, 0 failed, 41,233 subtests.

The docs-build baseline did move with the merges — 81 warning lines to 83 — and this branch still adds none, with the same two pre-existing docutils errors.

Awaiting fresh CI on the rebased head.

[JarryShaw]

Ready to merge at 913e54cba — closing the "awaiting fresh CI" on the rebase note above. CI is complete on the rebased head: 69 CheckRun legs green, 3 skipped, 0 failures, 0 in flight, mergeStateStatus CLEAN. The GOOD TO GO verdict carries from f89696fb2 on byte-identical patch evidence (md5 29bd56cb92b42a8569cae6e603ee4ad1 both sides), and nothing has been pushed since.

This is the last of #989's five pcapkit/ tranches — #1000, #1002, #1003, #1004 and this one. Once it lands, what remains on #989 is the changelog work that belongs to #657, which holds the only two bare Discussion citations.

Yours to merge.