docs(sphinx): define the wikipedia and iana extlinks roles ahead of first use

[JarryShaw]

Description

Defines :wikipedia: and :iana: in extlinks, alongside the three roles #998 added. Per the ruling
on #989: create them now rather than at first use. Neither is cited yet, deliberately.

Both templates come from measuring the tree:

• :wikipedia: → https://en.wikipedia.org/wiki/%s — 28 of the 31 distinct wikipedia.org/wikimedia.org
  URLs cited today are that shape, over 23 distinct articles (IPv6_packet appears four times,
  differing only by fragment). The other three must stay hardcoded through the conversion: a /w/index.php?…&oldid=… permalink, a foundation.wikimedia.org
  policy page in pcapkit/vendor/default.py, and an http:// ARP link a role would silently upgrade.
• :iana: → https://www.iana.org/assignments/%s, argument = the path after /assignments/. All
  179 distinct IANA URLs are that shape across 21 registries, so a registry index and a specific
  table both resolve through one role.

A two-%s IANA template would be wrong twice: over the 108 distinct fragment-stripped paths the
file stem equals the registry name in only 20 (the rest are per-table .csv files the vendor
crawlers read), and Python's % takes one argument, so the second placeholder raises at role-expansion
time rather than degrading. Captions are %s, not #%s, since the argument is a slug or path; prose
should use the explicit-title form, because a bare caption renders the raw path as visible text.

Why defining an uncited role is safe here

Not because an uncited role is inert — it is not. extlinks does not check the template at setup time,
but it registers ExternalLinksChecker unconditionally, and its check_uri loops every extlinks entry for every external reference with no
role usage involved. It returns early only because extlinks_detect_hardcoded_links is absent from this
tree and defaults to False. Measured: with that flag on, a page of hardcoded links and zero role
usages goes from 0 warnings to 1 purely by adding these entries. The comment in the diff says this
rather than the general claim an earlier revision made.

Verification

• Both roles render to the expected hrefs — fragment preserved, and both …/assignments/<registry> and
  …/assignments/<registry>/<file>.csv resolve. 0 unknown interpreted text role.
• Docs build exit 0, 61 warnings / 2 errors — baseline unchanged, compared as warning multisets.
• tests/project — 258 passed, 1 skipped, 859 subtests, 0 failed.

Checklist

• Commit type is in the subject line
• Tests pass locally
• Changelog entry — N/A, centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

[JarryShaw]

NEEDS CHANGES at 69571a5e8 — opus cross-review, a different model from the one that authored the
edit. It overturned a claim in my own commit, and I re-derived all three findings before posting.

1. The comment's mechanism claim is false. It says a role nobody writes is never invoked, so
defining it cannot change a build. sphinx/ext/extlinks.py registers ExternalLinksChecker
unconditionally; its check_uri loops config.extlinks.items() for every external reference, with no
role usage involved. Controlled, reproduced here: flag on, a page of hardcoded links and zero role
usages — entries absent 0 warnings, entries added 1 warning suggesting :wikipedia:. The build is
unaffected in this configuration only because extlinks_detect_hardcoded_links is absent from the
tree and defaults to False. Also real: the checker only matches when the captured value has no /,
so :wikipedia: would fire and :iana: never would.

2. "28 distinct Wikipedia articles, all of that shape" is two errors. The unit is URLs, not
articles — 28 URLs over 23 articles, IPv6_packet appearing four times by fragment alone. And
three cited URLs the template cannot express, which must stay hardcoded through the conversion:
en.wikipedia.org/w/index.php?title=…&oldid=…, foundation.wikimedia.org/wiki/Policy:… in
pcapkit/vendor/default.py, and an http:// ARP link the role would silently upgrade to https.

3. "20 of 108 distinct URLs" mislabels its unit. 20 of 108 holds over fragment-stripped paths;
over distinct URLs as written it is 91 of 179. The conclusion stands either way.

Unmoved: both templates render correctly, and the 61-warning / 2-error baseline — which it checked by
comparing warning multisets, not just counts, on both commits. Fix in flight; I will re-verify and
post a delta.

[JarryShaw]

Delta round: NEEDS CHANGES at cb1160f95, both fixed — now at 50fc4b347. Same opus reviewer,
resumed. It caught a new error I introduced while fixing the old one, which is exactly what a second
round is for.

1. My 34 was wrong; 31 is right. 28 of 31 distinct wikipedia.org/wikimedia.org URLs match
the template, so coverage is 90%, not 82%.

One correction to the review's reasoning, though its number is right. It attributed my 34 to a
regex that left trailing prose punctuation attached, producing three duplicate URLs. That is not what
happened: my host pattern was [a-z.]*wiki[a-z.]*\.org, which also matched wiki.wireshark.org —
three URLs on a host that is neither Wikipedia nor Wikimedia. 30 en.wikipedia.org + 1
foundation.wikimedia.org = 31, plus those 3 = my 34. Same conclusion, different cause, and the real
cause is the one worth remembering: an over-broad host pattern, not punctuation.

2. "extlinks validates nothing at setup time" overclaimed by one word — now "does not check the
template at setup time". Measured, roles never cited: a non-2-tuple entry gives ExtensionError: too many values to unpack and exit 2; a non-dict extlinks warns on type and exits 2. So structure is
validated at setup. Templates are not: no %s and two %s both build exit 0 with no message. The
distinction matters because the template being unchecked is the whole load-bearing point.

It also withdrew its earlier suggestion about the '/' not in value asymmetry, agreeing it belongs on
the PR rather than in the comment.

Re-verified at 50fc4b347: docs build exit 0, 61 warnings / 2 errors, 0 unknown-role, worktree root
in the log; tests/project 258 passed / 1 skipped / 859 subtests. The extlinks entries are unchanged
across all three revisions — md5-identical, per the reviewer's own check.

A fresh delta review on this head is next; not ready to merge until it lands.

[JarryShaw]

GOOD TO GO at 50fc4b347 — round-3 opus delta, resumed across all three rounds. Both round-2 fixes
hold, and it withdrew its own diagnosis on the point I disputed.

The 34 disagreement resolved, and the resolution is worth recording. Both explanations were
correct about different scans. My host pattern [a-z0-9.]*wiki[a-z.]*\.org matches
wiki.wireshark.org, pulling in three real citations (…/Development/LibpcapFileFormat#Global_Header,
…#Record_.28Packet.29_Header, …/Development/PcapNg) — 30 + 1 + 3 = my 34. Its own filter tested
'wikipedia.org' in host or 'wikimedia.org' in host, which never saw those three; what it saw was its
permissive-terminator variant, which also lands on 34, via three genuinely punctuation-attached
duplicates. Two unrelated artefacts inflating 31 by three apiece — which is exactly why reproducing a
number is not the same as explaining someone else's.

Re-verified by me at this head: 31 distinct wikipedia.org/wikimedia.org URLs, 28 matching
the template, 23 distinct articles. The corrected wording also closes the hole rather than just the
number, since naming the two hosts is what excludes the wireshark URLs.

Confirmed per claim: the setup-time wording is precise in both directions — setup_link_roles unpacks
the 2-tuple but inspects neither string, and make_link_role's %s comment describes a check the code
does not perform. Build at this head exit 0, 61 warnings / 2 errors, multisets identical to
e8a60d153, 0 unknown-role, 0 messages matching extlink|wikipedia|iana|hardcoded. extlinks dict
md5 19f4231280d1e0c231ed098ecdefee63 at all three revisions. tests/project 258 passed / 1 skipped /
859 subtests — re-run in its own worktree so the number is independently its.

One nit it raised and I am not acting on: the reworded line is 90 characters against the block's 87.
Nothing in the repo enforces a limit and the file already carries a 122-character line.

CI: 62 ok / 3 skipped / 0 failed / 6 running. Not ready to merge until those finish; I will say so
when they do.

[JarryShaw]

Ready to merge at 50fc4b347 — closing the "not yet" on the verdict above. mergeStateStatus
CLEAN, rollup SUCCESS, 69 ok / 3 skipped / 0 failed / 0 in flight. Required checks passed is
green and Compat Python 3.10-3.14 all passed, with 3.15 (scheduled) skipped as always.

Three review rounds, all of them on prose: the two extlinks entries never changed once, md5
19f4231280d1e0c231ed098ecdefee63 identical at 69571a5e8, cb1160f95 and 50fc4b347. What the
rounds actually fixed was a false mechanism claim in the comment, two mislabelled units, and one
number — none of which CI could ever have caught, which is the argument for the cross-review existing.

Unpublished and nothing merged by me: this is yours to merge.