docs(schema): convert bare citations to the issue role in docstrings

pcapkit/protocols/application/ftp.py

@@ -42,7 +42,7 @@ class Type(EnumLookup, StrEnum):
     """FTP packet type.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #877's ruling that every non-registry enumeration shares that
+    issue :issue:`877`'s ruling that every non-registry enumeration shares that
     lookup contract -- pure re-parenting, since this class defines neither
     ``get`` nor ``_missing_`` of its own to reconcile with the base.
 

pcapkit/protocols/application/http.py

@@ -37,7 +37,7 @@
 #: message can begin with it and a prefix compare cannot false-positive on one.
 #: That is what makes it a positive identification rather than a heuristic, and
 #: it is why :meth:`HTTP._guess_version` tests it before attempting any parse
-#: (#800).
+#: (:issue:`800`).
 _HTTP2_PREFACE = b'PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n'
 
 
@@ -60,7 +60,7 @@ class HTTP(Application[_PT, _ST], Generic[_PT, _ST]):
     #: :attr:`length`; without that, ``ProtocolBase.__init__``'s
     #: ``self._info.__update__(packet=self.packet.payload)`` slices the payload
     #: from octet 9 of a buffer whose frame starts at octet 24 and reports the
-    #: tail of the preface as packet payload. See #800.
+    #: tail of the preface as packet payload. See :issue:`800`.
     _preface_length = 0
 
     #: This class is a version dispatcher rather than a protocol with a header of
@@ -71,7 +71,7 @@ class HTTP(Application[_PT, _ST], Generic[_PT, _ST]):
     #: according to that value -- so the set of names that is correct here depends
     #: on an argument. :obj:`None` therefore opts out of the construction keyword
     #: check that :meth:`ProtocolBase.__init__
-    #: <pcapkit.protocols.protocol.ProtocolBase.__init__>` performs (#617); the
+    #: <pcapkit.protocols.protocol.ProtocolBase.__init__>` performs (:issue:`617`); the
     #: two versioned classes are checked normally when constructed directly.
     __keywords__ = None
 
@@ -219,14 +219,14 @@ def _guess_version(self, length: 'int', **kwargs: 'Any') -> 'HTTP':
         """Identify the HTTP version of the payload, and parse it with that version.
 
         The payload is *identified* first and trial-parsed only as a last resort.
-        Until #800 there was no identification step at all: both versions were
+        Until :issue:`800` there was no identification step at all: both versions were
         tried in turn and whichever parser did not object was taken as the
         answer, which answers "did a parser accept this?" where the question is
         "what is this?" -- and got both directions wrong. The HTTP/2 connection
         preface came back ``version='2'`` only because ``httpv2.HTTP`` read its
         leading ``b'PRI'`` as a 24-bit declared frame length of 5,265,993, and
         ``b'foo bar baz\\r\\nX: y\\r\\n\\r\\n'`` -- not HTTP at all -- came back
-        ``version='2'`` the same way. #799 closed the second of those by
+        ``version='2'`` the same way. :issue:`799` closed the second of those by
         requiring a frame's declared length to be backed by its buffer, but that
         left the preface *unidentifiable*: a real HTTP/2 connection opening is
         refused by both arms and reported as not-HTTP.

pcapkit/protocols/application/httpv1.py

@@ -78,7 +78,7 @@ def _test_start_line(data: 'bytes') -> 'bool':
 
     This is a *classification* predicate and parses nothing: it answers "is this
     HTTP/1?" for :meth:`HTTP._guess_version
-    <pcapkit.protocols.application.http.HTTP._guess_version>`, which until #800
+    <pcapkit.protocols.application.http.HTTP._guess_version>`, which until :issue:`800`
     answered that question by trial-parsing every version in the family and
     keeping whichever one did not object -- so a payload that is not HTTP at all
     was classified by which parser happened to fail less loudly.
@@ -142,7 +142,7 @@ class Type(EnumLookup, StrEnum):
     """HTTP packet type.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #877's ruling that every non-registry enumeration shares that
+    issue :issue:`877`'s ruling that every non-registry enumeration shares that
     lookup contract -- pure re-parenting, since this class defines neither
     ``get`` nor ``_missing_`` of its own to reconcile with the base.
 

pcapkit/protocols/application/httpv2.py

@@ -223,7 +223,7 @@ def unpack(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_HTTP'
             fixed ``stream`` and ``error`` fields alone consume eight); that
             residual is why :meth:`HTTP._guess_version
             <pcapkit.protocols.application.http.HTTP._guess_version>` still
-            suppresses :exc:`struct.error` on its last arm. See #799.
+            suppresses :exc:`struct.error` on its last arm. See :issue:`799`.
 
             ``length`` is resolved against :func:`len` only for *this*
             method's own check, and the *original* argument -- ``None``

pcapkit/protocols/application/ngap.py

@@ -201,7 +201,7 @@ class PDUKind(EnumLookup, StrEnum):
     |pycrate|_ resolves by value.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #877's ruling that every non-registry enumeration shares that
+    issue :issue:`877`'s ruling that every non-registry enumeration shares that
     lookup contract -- pure re-parenting, since this class defines neither
     ``get`` nor ``_missing_`` of its own to reconcile with the base.
 
@@ -223,11 +223,11 @@ class Criticality(EnumLookup, IntEnum):
     by |pycrate|_ through the standard member map. The values are the
     ``ENUMERATED`` indices, which is what goes on the wire.
 
-    Carries no ``get`` of its own. GitHub issue #877 re-parented this class onto
+    Carries no ``get`` of its own. GitHub issue :issue:`877` re-parented this class onto
     :class:`~pcapkit.corekit.enum.EnumLookup` and kept a delegating override for
     one reason only: it converted the base's name-miss :exc:`KeyError` into a
     :exc:`ValueError`, so that an unknown *name* and an unknown *value* reported
-    identically. GitHub issue #923's ruling retired that conversion -- a name
+    identically. GitHub issue :issue:`923`'s ruling retired that conversion -- a name
     miss is :exc:`KeyError`-shaped, exactly as ``E['nosuch']`` is on a stdlib
     :class:`~enum.Enum` -- which left the override a pure pass-through, so it
     went with it.

pcapkit/protocols/data/internet/hip.py

@@ -209,7 +209,7 @@ class PuzzleParameter(Parameter):
     #: exact width of ``Random #I``. Declared rather than recomputed from
     #: :meth:`int.bit_length`, which cannot see a leading zero octet: without it
     #: a parameter read with ``Length = 12`` re-serialised as ``Length = 5``.
-    #: See #653.
+    #: See :issue:`653`.
     rhash_len: 'int'
 
     if TYPE_CHECKING:
@@ -227,7 +227,7 @@ class SolutionParameter(Parameter):
     #: Carried verbatim rather than interpreted, so that re-serialising a parsed
     #: parameter reproduces the octet it arrived with. It used to be read as a
     #: ``PUZZLE`` ``Lifetime``, which only :rfc:`7401#section-5.2.4` defines, and
-    #: the conformant ``0x00`` then could not be re-serialised at all. See #654.
+    #: the conformant ``0x00`` then could not be re-serialised at all. See :issue:`654`.
     reserved: 'int'
     #: Solution data.
     opaque: 'bytes'
@@ -241,7 +241,7 @@ class SolutionParameter(Parameter):
     #: width of both fields. Declared rather than recomputed from
     #: :meth:`int.bit_length`, which cannot see a leading zero octet: without it a
     #: parameter read with ``Length = 20`` re-serialised as ``Length = 6``.
-    #: See #653.
+    #: See :issue:`653`.
     rhash_len: 'int'
 
     if TYPE_CHECKING:

pcapkit/protocols/link/arp.py

@@ -406,7 +406,7 @@ def _make_proto_resolve(self, addr: 'IPv4Address | IPv6Address | str | bytes', p
             directly, because :obj:`bool` is an :class:`int` subclass that
             either constructor accepts without complaint. Before this,
             ``addr=True`` packed as ``00000001`` (IPv4) or ``::1`` (IPv6) with
-            no exception and no warning at all (c.f. #508, #540).
+            no exception and no warning at all (c.f. :issue:`508`, :issue:`540`).
 
             The description below uses :attr:`self.__class__.__name__
             <type.__name__>` rather than :attr:`self.alias

pcapkit/protocols/link/l2tp.py

@@ -42,7 +42,7 @@
 different framing decision. It also means v3 is the first member of this family
 to have a real :meth:`~pcapkit.protocols.protocol.Protocol.__index__`.
 
-GitHub issue #548 proposed closing that gap by binding
+GitHub issue :issue:`548` proposed closing that gap by binding
 :class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` at 115 instead, which does not
 work and is worth recording so it is not proposed again. Over IP the v3 session
 header is, in :rfc:`3931` §4.1.1's own words, *"free of any restrictions imposed

pcapkit/protocols/link/l2tpv2.py

@@ -98,7 +98,7 @@ class L2TPv2(L2TP[Data_L2TP, Schema_L2TP],
         references :rfc:`3931`, i.e. **L2TPv3**, whose session and control
         message headers are a different shape -- so the binding waits on an
         ``L2TPv3`` class rather than on this one. Binding *this* class there was
-        proposed in GitHub issue #548 and does not work: over IP the v3 session
+        proposed in GitHub issue :issue:`548` and does not work: over IP the v3 session
         header carries no version nibble at all, so this class cannot recognise
         that the datagram is not its own. See
         :class:`~pcapkit.protocols.link.l2tp.L2TP` for the measurement.

pcapkit/protocols/link/ospf.py

@@ -336,8 +336,8 @@ def _make_id_numbers(self, id: 'IPv4Address | str | bytes | bytearray') -> 'byte
             straight from its own arguments), so the only caller is a unit
             test. It is routed through :func:`parse_ip_address` anyway, so
             that it does not resurface the defect the moment a caller
-            reaches it -- the same kind of omission is how #469's single-site
-            fix survived to become #491 and then #508 (c.f. #540).
+            reaches it -- the same kind of omission is how :issue:`469`'s single-site
+            fix survived to become :issue:`491` and then :issue:`508` (c.f. :issue:`540`).
 
             The description below uses :attr:`self.__class__.__name__
             <type.__name__>` rather than :attr:`self.alias

pcapkit/protocols/misc/pcapng.py

@@ -250,7 +250,7 @@ class PacketDirection(EnumLookup, enum.IntEnum):
     """Packet direction for ``epb_flags`` options.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #877's ruling that every non-registry enumeration shares that
+    issue :issue:`877`'s ruling that every non-registry enumeration shares that
     lookup contract -- pure re-parenting, since this class defines neither
     ``get`` nor ``_missing_`` of its own to reconcile with the base.
 
@@ -268,7 +268,7 @@ class PacketReception(EnumLookup, enum.IntEnum):
     """Reception type for ``epb_flags`` options.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #877's ruling that every non-registry enumeration shares that
+    issue :issue:`877`'s ruling that every non-registry enumeration shares that
     lookup contract -- pure re-parenting, since this class defines neither
     ``get`` nor ``_missing_`` of its own to reconcile with the base.
 
@@ -314,7 +314,7 @@ class WireGuardKeyLabel(EnumLookup, StrEnum):
     """WireGuard key log label.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #877's ruling that every non-registry enumeration shares that
+    issue :issue:`877`'s ruling that every non-registry enumeration shares that
     lookup contract -- pure re-parenting, since this class defines neither
     ``get`` nor ``_missing_`` of its own to reconcile with the base.
 
@@ -721,7 +721,7 @@ def length(self) -> 'int':
             :attr:`ProtocolBase.length <pcapkit.protocols.protocol.ProtocolBase.length>`
             does not distinguish them, but a PCAP-NG block carries a trailer.
             :attr:`self.packet <packet>` is overridden accordingly; see there and
-            #646.
+            :issue:`646`.
 
         """
         return self._info.length
@@ -759,7 +759,7 @@ def packet(self) -> 'Data_Packet':
         packet block reported ``packet == b''`` while ``captured_len`` declared
         hundreds of octets, and dumping such a block through
         :class:`~pcapkit.dumpkit.pcap.PCAPIO` wrote a record header promising
-        octets it then did not write. See #646.
+        octets it then did not write. See :issue:`646`.
 
         The payload is therefore the block schema's
         :attr:`~pcapkit.protocols.schema.schema.Schema.__payload__` field, which
@@ -1308,11 +1308,9 @@ def _check_block_floor(self, length: 'Optional[int]') -> 'None':
         of nothing ``__length__`` is negative -- which
         :func:`~pcapkit.protocols.schema.misc.pcapng.pcapng_block_selector` hands
         to :class:`~pcapkit.corekit.fields.misc.SchemaField`, where
-        :meth:`io.RawIOBase.read` raises the bare ``ValueError`` of `#678
-        <https://github.com/JarryShaw/PyPCAPKit/issues/678>`__.
+        :meth:`io.RawIOBase.read` raises the bare ``ValueError`` of :issue:`678`.
 
-        Reporting the end of the stream instead is what keeps the `#431
-        <https://github.com/JarryShaw/PyPCAPKit/issues/431>`__ accommodation:
+        Reporting the end of the stream instead is what keeps the :issue:`431` accommodation:
         :exc:`~pcapkit.utilities.exceptions.StreamEOFError` is an
         :exc:`EOFError`, which :meth:`Extractor.record_frames
         <pcapkit.foundation.extraction.Extractor.record_frames>` already catches
@@ -1387,7 +1385,7 @@ def _get_local_timezone() -> 'timezone':
             Not used when reconstructing a block timestamp, and must not be:
             a PCAP-NG timestamp is an offset from the UNIX epoch, so mixing the
             *reading* host's zone into it makes one file parse to different
-            instants on different machines (see #361).
+            instants on different machines (see :issue:`361`).
             :meth:`self._get_timezone <_get_timezone>` returns
             :attr:`datetime.timezone.utc` instead when the capture names no
             ``if_tzone``.
@@ -1607,7 +1605,7 @@ def _make_timestamp(self, timestamp: 'Optional[float | Decimal | dt_type | int]'
             used to promise a "timezone conversion" that the code never
             performed, which made it look as though the read side's timezone
             shift had a counterpart here (it did not, so a read followed by a
-            write drifted by the host's UTC offset -- see #361).
+            write drifted by the host's UTC offset -- see :issue:`361`).
 
         """
         with localcontext(prec=64):

pcapkit/protocols/schema/application/httpv2.py

@@ -128,12 +128,12 @@ class Flags(EnumLookup, enum.IntFlag):
         """Flags enumeration for HTTP/2 frames.
 
         Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per
-        GitHub issue #877's ruling that every non-registry enumeration
+        GitHub issue :issue:`877`'s ruling that every non-registry enumeration
         shares that lookup contract. The six concrete per-frame subclasses
         below each declare ``class Flags(FrameType.Flags):`` with no base
         list of their own, so they inherit :class:`EnumLookup` transitively
         through this one re-parent rather than needing it repeated --
-        verified at runtime for GitHub issue #877 (see the session report),
+        verified at runtime for GitHub issue :issue:`877` (see the session report),
         not merely assumed from the MRO rules.
 
         """