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

pcapkit/const/ftp/command.py

@@ -34,12 +34,12 @@ class FEATCode(EnumRegistry, StrEnum):
        keywords generated after them (data-driven, not hand-picked; see
        :meth:`~pcapkit.vendor.ftp.command.Command.process`) -- rather than
        minting the per-command ones at import time as an incidental side
-       effect of building :class:`Command`'s own rows. GitHub issue #860:
-       that import-time mutation was the same defect shape #775 removed
+       effect of building :class:`Command`'s own rows. GitHub issue :issue:`860`:
+       that import-time mutation was the same defect shape :issue:`775` removed
        from :class:`~pcapkit.const.pcapng.filter_type.FilterType`, just not
        previously noticed here. ``_missing_`` still unmints for a keyword that
        turns up on the wire but names none of these -- the extendability the
-       owner conditionally asked to keep on GitHub issue #860: unsure what a
+       owner conditionally asked to keep on GitHub issue :issue:`860`: unsure what a
        FEAT value absent from the RFC's list means in the CSV table, the owner
        said that if the expected handling is our current approach, as industry
        convention has it, the registry stays extendable as is, and then approved
@@ -99,7 +99,7 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode':
         """Resolve ``key`` case-insensitively, per :rfc:`5797#section-2`.
 
         One of the few case-insensitive overrides the ruling on GitHub issue
-        #877 allows, and the registry's own defining document states the
+        :issue:`877` allows, and the registry's own defining document states the
         comparison rule outright rather than leaving it to be inferred --
         :rfc:`5797#section-2`, on the ``FEAT Code`` column this class is
         generated from: *"IANA maintains uniqueness of feature names (FEAT
@@ -119,15 +119,15 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode':
         lower case -- measured on the IANA CSV: 10 distinct all-upper-case
         keywords against ``base``, ``feat``, ``hist``, ``nat6`` and ``secu``,
         with none mixed. Without this override ``get('BASE')`` raised
-        :exc:`KeyError`, which is the defect GitHub issue #903's audit found.
+        :exc:`KeyError`, which is the defect GitHub issue :issue:`903`'s audit found.
 
         The obvious objection, answered: :rfc:`5797` uses case *presentationally*
         to tell a real keyword from a placeholder -- *"defined FEAT keywords
         codes are listed in all uppercase, whereas placeholder keywords ... are
         listed in lowercase"* -- so folding might look like it discards that
         distinction. It does not. Only the inbound ``key`` is folded; every
         member keeps the registrar's own casing, and the fold itself is backed by
-        the RFC: the final ruling on GitHub issue #877 is that an enum treats its
+        the RFC: the final ruling on GitHub issue :issue:`877` is that an enum treats its
         values as case-insensitive where the RFC states they are, and as
         case-sensitive otherwise. So ``get('BASE').name`` is still ``'base'`` and
         still says placeholder. And the uniqueness rule quoted above is what makes
@@ -191,7 +191,7 @@ class CommandType(EnumLookup, IntFlag):
     """Type of "kind" of command, based on :rfc:`959#section-4`.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #930, finishing #877's phase 2. Pure re-parenting as far as
+    issue :issue:`930`, finishing :issue:`877`'s phase 2. Pure re-parenting as far as
     ``get``/``get_all`` are concerned -- this class defines no ``get`` of its
     own to reconcile with the base -- and its own :meth:`_missing_` range
     guard below is untouched, since :class:`EnumLookup` does not touch that
@@ -225,7 +225,7 @@ class ConformanceRequirement(EnumLookup, IntEnum):
     """Expectation for support in modern FTP implementations.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #930, finishing #877's phase 2 -- pure re-parenting, since this
+    issue :issue:`930`, finishing :issue:`877`'s phase 2 -- pure re-parenting, since this
     class defines neither ``get`` nor ``_missing_`` of its own to reconcile
     with the base.
 
@@ -245,7 +245,7 @@ class Command(EnumRegistry, StrEnum):
     .. note::
 
        Neither ``_missing_`` nor ``get()`` mints any more. The owner ruled on
-       GitHub issue #860 that ``get`` should not mint: only IANA-registered
+       GitHub issue :issue:`860` that ``get`` should not mint: only IANA-registered
        values are legitimate members, a new one is properly created through
        :meth:`register`, and ``get`` is not given enough information to create
        one. Concretely true here -- a bare wire command word carries no
@@ -490,7 +490,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Command':
             name: Bare label for the unregistered member -- here, the
                 canonical upper-case form of ``value``, matching the name
                 every *registered* member of this class is looked up by,
-                since #860's open-vocabulary registries have no manufactured
+                since :issue:`860`'s open-vocabulary registries have no manufactured
                 placeholder label to fall back to.
 
         """

pcapkit/const/http/method.py

@@ -27,7 +27,7 @@ class Method(EnumRegistry, StrEnum):
     .. note::
 
        Neither ``_missing_`` nor ``get()`` mints any more. The owner ruled on
-       GitHub issue #860 that ``get`` should not mint: only IANA-registered
+       GitHub issue :issue:`860` that ``get`` should not mint: only IANA-registered
        values are legitimate members, a new one is properly created through
        :meth:`register`, and ``get`` is not given enough information to create
        one. Concretely true here -- a bare wire method verb carries no
@@ -202,14 +202,14 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Method':
                 identifier, not the value -- is canonicalised.
 
                 A *registered* member of this class used to carry something
-                different here: GitHub issue #870 found that
+                different here: GitHub issue :issue:`870` found that
                 :meth:`__new__` called ``str.__new__(cls)`` with no
                 argument at all, so every one of the 40 declared members'
                 own :class:`str` payload was permanently empty regardless
                 of ``value`` (``str(Method.GET) == ''``, and
                 ``Method.GET == 'GET'`` was :obj:`False`) -- true on
                 ``main`` at ``60b85e3a4`` as well as when this docstring
-                was first written. #870 fixed :meth:`__new__` to
+                was first written. :issue:`870` fixed :meth:`__new__` to
                 ``str.__new__(cls, value)``, mirroring
                 :class:`~pcapkit.const.ftp.command.Command`'s own
                 ``__new__``, so a registered member's payload now agrees
@@ -219,7 +219,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Method':
             name: Bare label for the unregistered member -- here, the
                 canonical upper-case form of ``value``, matching the name
                 every *registered* member of this class is looked up by,
-                since #860's open-vocabulary registries have no manufactured
+                since :issue:`860`'s open-vocabulary registries have no manufactured
                 placeholder label to fall back to.
 
         """
@@ -233,7 +233,7 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method':
         """Backport support for original codes.
 
         Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for the
-        lookup itself, per GitHub issue #908: the previous override checked
+        lookup itself, per GitHub issue :issue:`908`: the previous override checked
         only ``_member_map_`` (names), never ``_value2member_map_``
         (values), so the two IANA methods whose member *name* differs from
         their *value* -- ``BASELINE_CONTROL`` / ``'BASELINE-CONTROL'`` and
@@ -246,7 +246,7 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method':
         (:meth:`~pcapkit.corekit.enum.EnumLookup.get`), and a zero-argument
         ``super()`` needs a first argument to bind, so this override had to
         move from :class:`staticmethod` to :class:`classmethod` to delegate
-        at all -- see GitHub issue #908's own correction of the fix it
+        at all -- see GitHub issue :issue:`908`'s own correction of the fix it
         originally proposed. Callers are unaffected by the switch itself:
         ``Method.get('X')`` binds identically either way.
 
@@ -270,19 +270,19 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method':
                 and values, via the base's own precedence -- name before
                 value -- so a value-only match such as
                 ``'BASELINE-CONTROL'`` now resolves too, closing GitHub
-                issue #908.
+                issue :issue:`908`.
             default: Value for the unregistered member built when ``key``
                 matches neither a name nor a value. ``None``, the
                 default, uses ``key`` itself -- unchanged from before
-                GitHub issue #908.
+                GitHub issue :issue:`908`.
 
         Raises:
             ValueError: If ``key`` is not a :class:`str`. This reaches the
                 caller from the base's non-``str`` branch, which calls
                 ``cls(key)`` and so ``_missing_``, and is **not** caught by
                 the ``except KeyError`` fallback below -- only a failed
                 *name* lookup is. The non-``str`` surface therefore moved
-                with GitHub issue #908: ``get(42)`` and ``get(None)`` used
+                with GitHub issue :issue:`908`: ``get(42)`` and ``get(None)`` used
                 to raise :exc:`AttributeError` from ``key.upper()``, and
                 ``get(b'GET')`` used to *return* a member whose name and
                 value were both the :class:`bytes` object. Raising is the
@@ -317,7 +317,7 @@ def _missing_(cls, value: 'str') -> 'Method':
                 the canonical upper-case member names -- deliberately unlike
                 :meth:`get`, which is case-**sensitive** per
                 :rfc:`9110#section-9.1`. The split was ruled deliberate on
-                GitHub issue #896; GitHub issue #908 is the pointer between
+                GitHub issue :issue:`896`; GitHub issue :issue:`908` is the pointer between
                 the two, so a reader of this one file is not left with two
                 contradictory rationales and nothing tying them together.
 

pcapkit/const/ngap/__init__.py

@@ -20,7 +20,7 @@
 :mod:`pcapkit.vendor.ngap.procedure_code` and
 :mod:`pcapkit.vendor.ngap.protocol_ie`, which source the assignment from
 |pycrate|_'s compiled NGAP specification rather than a network registry --
-see that module's docstring for why, and GitHub issue #880 for the ruling.
+see that module's docstring for why, and GitHub issue :issue:`880` for the ruling.
 
 .. [*] 3GPP TS 38.413
 .. [*] 3GPP TS 38.413

pcapkit/const/reg/apptype/apptype.py

@@ -89,7 +89,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
         """Backport support for original codes.
 
         Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for GitHub
-        issue #877's re-parenting, but keeps this override rather than dropping
+        issue :issue:`877`'s re-parenting, but keeps this override rather than dropping
         it, for one behaviour the base does not reproduce on its own: **case
         folding**. This class has always matched a name case-insensitively
         (``key.lower()``); the base's own ``str`` branch is case-sensitive.
@@ -100,12 +100,12 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
         Case folding is now the *only* thing this override adds. It used to
         convert the base's name-miss exception as well -- this class raised
         :exc:`ValueError` where the base raised :exc:`KeyError` -- and the
-        ruling given in review of the work for #877, implemented in GitHub issue
-        #923, retired that conversion: the exception is to follow what stdlib's
+        ruling given in review of the work for :issue:`877`, implemented in GitHub issue
+        :issue:`923`, retired that conversion: the exception is to follow what stdlib's
         ``Enum`` would raise in the circumstances, :exc:`ValueError` or
         :exc:`KeyError` as the case may be, and is to come from
         :mod:`pcapkit.utilities.exceptions` rather than being a builtin. A
-        stdlib ``E['nosuch']`` raises :exc:`KeyError`, and #923's census of the
+        stdlib ``E['nosuch']`` raises :exc:`KeyError`, and :issue:`923`'s census of the
         127 concrete :class:`~pcapkit.corekit.enum.EnumLookup` subclasses --
         taken before the phase-2 re-parenting moved this class, so it is not
         among them -- found 119 already answering a name miss that way against 5
@@ -115,17 +115,17 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
         rather than from any name-miss policy. So there was no policy here to
         preserve, and a name miss now reaches the caller as
         :exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The
-        maintainer's ruling given in review of the work for #808, that
+        maintainer's ruling given in review of the work for :issue:`808`, that
         :class:`TransportProtocol` is not to be extended at all, is untouched by
         that: the refusal is still a refusal and still mints nothing, only its
         exception class moved.
 
         The base is a :class:`classmethod`
         (:meth:`~pcapkit.corekit.enum.EnumLookup.get`), so this override
         moves from :class:`staticmethod` to :class:`classmethod` to
-        delegate at all -- the same move GitHub issue #908 made for
+        delegate at all -- the same move GitHub issue :issue:`908` made for
         :meth:`~pcapkit.const.http.method.Method.get`. Grepped every call
-        site in this tree for GitHub issue #877: all call this method by
+        site in this tree for GitHub issue :issue:`877`: all call this method by
         name, none take it as a bare callable or introspect ``__func__``,
         so the switch is not caller-visible.
 
@@ -154,7 +154,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
         Raises:
             EnumKeyError: If ``key`` names no member and there is no usable
                 ``default``. A :exc:`KeyError`, from the base, since GitHub
-                issue #923 -- it used to be a plain :exc:`ValueError` raised
+                issue :issue:`923` -- it used to be a plain :exc:`ValueError` raised
                 here.
             EnumValueError: If ``key`` is a value no member carries and there
                 is no usable ``default``. A :exc:`ValueError`, from the base.
@@ -2430,7 +2430,7 @@ def __new__(cls, value: 'int', name: 'str' = '<null>',
     def aliases(self) -> 'tuple[AppType, ...]':
         """Other services sharing :attr:`port` in this member's own registry.
 
-        GitHub issue #807. No storage of its own: IANA already keeps every
+        GitHub issue :issue:`807`. No storage of its own: IANA already keeps every
         colliding service as its own member of :data:`__registry__`, keyed on
         the shared port -- :meth:`get_all` already walks that same bucket to
         answer with the aliases after the canonical member, so this is exactly
@@ -2518,16 +2518,16 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[
                 every entry point rejects a non-port identically.
             proto: Transport protocol, as a member, its name, or a bare
                 :class:`int`. That last shape is not merely defensive: GitHub
-                issue #808 dropped ``TransportProtocol``'s ``IntFlag`` base, so
+                issue :issue:`808` dropped ``TransportProtocol``'s ``IntFlag`` base, so
                 ``TransportProtocol.a | TransportProtocol.b`` -- built by hand,
                 the same as any caller passing a literal port-transport bitmask
                 -- falls through to ``int.__or__`` and returns a bare
                 :class:`int` rather than a member. Never split back into the
                 transports its bits would each name -- a ruling given in review
-                of the work for #808 -- so it is looked up as the one whole
+                of the work for :issue:`808` -- so it is looked up as the one whole
                 value it already is, exactly like any other bare int: refused
                 when that whole value names no registry, resolved when it
-                happens to equal one instead. Since GitHub issue #860 moved
+                happens to equal one instead. Since GitHub issue :issue:`860` moved
                 this class off power-of-two spacing, a hand-built composite
                 is no longer guaranteed to be the former -- see
                 :meth:`_dispatch`'s own body for a value that resolves.
@@ -2755,7 +2755,7 @@ def register(cls, port: 'int', name: 'str') -> 'AppType':  # pylint: disable=arg
         ``port`` to already carry a member and adds a further name for it;
         this requires the opposite -- ``port`` unclaimed in this registry --
         and mints the first. :meth:`get` can no longer do this itself as of
-        GitHub issue #860 (the owner's ruling there: only IANA-registered values
+        GitHub issue :issue:`860` (the owner's ruling there: only IANA-registered values
         are legitimate, a new entry is properly created through :meth:`register`,
         and ``get`` lacks the information to create one), so this is now the only
         way to add a service this registry does not already carry.
@@ -2812,7 +2812,7 @@ def register(cls, port: 'int', name: 'str') -> 'AppType':  # pylint: disable=arg
     def register_alias(cls, port: 'int', name: 'str') -> 'AppType':  # pylint: disable=arguments-renamed
         """Register ``name`` as a new alias on ``port``, in this registry alone.
 
-        GitHub issue #807's third ask, deliberately scoped to **this**
+        GitHub issue :issue:`807`'s third ask, deliberately scoped to **this**
         per-transport registry: ``TCP.register_alias(...)`` never touches
         :class:`UDP`'s members, which is what keeps an alias registered on one
         transport from leaking onto a transport IANA never assigned it -- e.g.

pcapkit/vendor/__main__.py

@@ -51,7 +51,7 @@ def get_parser() -> 'ArgumentParser':
 def _snapshot_and_restore(vendor: 'Type[Vendor]') -> 'Iterator[None]':
     """Copy a target's const file aside before it runs; restore it if it raises.
 
-    A ruling given in review of the work for #872 settled how a failed target
+    A ruling given in review of the work for :issue:`872` settled how a failed target
     is undone: keep a copy of its const file before running the sub-vendor and
     revert if anything failed, rather than making the write itself atomic.
     This is that -- at the per-target boundary :func:`run` already owns, which
@@ -100,7 +100,7 @@ def _snapshot_and_restore(vendor: 'Type[Vendor]') -> 'Iterator[None]':
     not backed up stops the target before it starts. Both leave the
     previous file exactly as it was, for different reasons.
 
-    A symlinked destination has a related divergence from the pre-#872
+    A symlinked destination has a related divergence from the pre-:issue:`872`
     behaviour -- documented against the write path by rounds 4-8 (deleted
     along with ``_write_atomic``, though the underlying behaviour persists
     here instead): ``open(const_file, 'w')`` writes *through* a symlink,