From 50fc4b3477489e1f79aa8b9ec69b68f5d4242d58 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sat, 3 Oct 2026 02:07:04 -0400 Subject: [PATCH] docs(sphinx): define the wikipedia and iana extlinks roles ahead of first use Adds two entries alongside the three added in #998, so that the citations these pages already carry as bare URLs have a role to convert to when that sweep reaches them. - `:wikipedia:` expands `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: a `/w/index.php?...&oldid=...` permalink, a `foundation.wikimedia.org` policy page in `pcapkit/vendor/default.py`, and an `http://` ARP link that a role would silently upgrade to `https`. - `:iana:` expands `https://www.iana.org/assignments/%s`, the argument being the path after `/assignments/`. All 179 distinct IANA URLs are that shape across 21 registries, so both a registry index and a specific table resolve through one role. A two-`%s` IANA template would be wrong: 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. Both captions are `%s`, not `#%s`, because the argument is a slug or path rather than a number; prose should use the explicit-title form, since a bare caption renders the raw path as visible text. Neither role is cited yet, by design, per the ruling on #989. Verified: both roles render to the expected hrefs with the fragment and both IANA shapes intact; docs build exit 0 with 61 warnings / 2 errors, unchanged from the baseline, and 0 unknown-role errors; `tests/project` 258 passed, 1 skipped, 859 subtests. --- docs/source/conf.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 3f050af1c..b9d628ae0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -108,10 +108,22 @@ # ``:discussion:`` is needed because a handful of cited numbers are GitHub # Discussions rather than issues -- the issues API returns 404 for them, so # ``:issue:`` would link to a page that does not exist. +# +# ``:wikipedia:`` and ``:iana:`` are defined ahead of their first use, deliberately. +# ``extlinks`` does not check the template at setup time, and the ``ExternalLinksChecker`` +# post-transform that does read every entry, cited or not, returns early while +# ``extlinks_detect_hardcoded_links`` stays at its default ``False``. So in this +# configuration an uncited role does not change the build; that is not a general law. +# Their argument is a slug or a path rather than a number, hence the ``%s`` caption, +# and the ``:iana:`` argument is the path after ``/assignments/``. Prose should give an +# explicit title, ``:iana:`ARP parameters ```, +# since the bare caption renders the raw slug or path as the visible text. extlinks = { 'issue': ('https://github.com/JarryShaw/PyPCAPKit/issues/%s', '#%s'), 'pr': ('https://github.com/JarryShaw/PyPCAPKit/pull/%s', '#%s'), 'discussion': ('https://github.com/JarryShaw/PyPCAPKit/discussions/%s', '#%s'), + 'wikipedia': ('https://en.wikipedia.org/wiki/%s', '%s'), + 'iana': ('https://www.iana.org/assignments/%s', '%s'), } intersphinx_mapping = {