docs: display Protocol in ProtocolBase member cross-references (#1103)

The owner refined the #1103 ruling: a `ProtocolBase.<member>` reference should
read `Protocol.<member>` in the rendered docs, for one consistent public
vocabulary, while the link still targets the `ProtocolBase` attribute. That is
the split-display-target form, `:meth:`Protocol.X <...protocol.ProtocolBase.X>``,
applied across everything Sphinx renders.

* 46 reference sites in `pcapkit/` and `docs/source/` now display
  `Protocol.<member>`. 37 keep their `ProtocolBase` target, which is the
  requested form; the other 9 already targeted `Protocol` -- #2420 moved those
  targets but left the display text reading `ProtocolBase` -- and are now
  display-consistent too.
* Three short-form references in `protocol.py` gained an explicit
  fully-qualified target, so the display text could change without repointing
  the link: `:meth:`ProtocolBase._parse_next_layer`` is now
  `:meth:`Protocol._parse_next_layer <...ProtocolBase._parse_next_layer>``.
* `__init_subclass__` keeps displaying `ProtocolBase` (6 sites). `Protocol`
  defines its own override, so displaying `Protocol` there would name a
  different method than the link resolves to.
* Two further sites keep `ProtocolBase` because the adjacent prose would
  otherwise contradict itself: `schema.py`'s comment reads "``ProtocolBase``,
  not ``Protocol``" two lines above its reference, and
  `protocol-layer-placement.rst` asserts `OSPF.__proto__` *is* that attribute
  inside a paragraph analysing MRO set-difference.
* The `Raises:` clause of `register` is unchanged. It names the class the
  guard's `issubclass` actually tests, not a member whose documentation is
  being pointed at, and `tests/protocols/test_register_class_guard_unit.py`
  asserts that wording (#2316/#1016).
* `tests/` and `examples/` are untouched (28 sites). Their docstrings are not
  part of the Sphinx render, so the display rationale does not reach them.

No link was repointed: a guard canonicalises every role target before and
after and reports them identical, bar the three short-form expansions, which
resolve to the same object. An AST-structure guard (`ast.dump` with docstrings
stripped) confirms all 26 touched `.py` files are prose-only.

Author: JarryShaw

docs/source/ext.rst

@@ -241,13 +241,13 @@ The following code snippet shows how to create a new protocol class:
    silently wrong field. The accepted set is read from :func:`inspect.signature` -- the union of every
    keyword-taking parameter of ``make``, ``read``, ``pack``, ``unpack``,
    ``__post_init__`` and ``__init__`` anywhere in the class's MRO -- which is
-   wider than ``make`` alone because :meth:`ProtocolBase.__post_init__
+   wider than ``make`` alone because :meth:`Protocol.__post_init__
    <pcapkit.protocols.protocol.ProtocolBase.__post_init__>` hands the same
    ``**kwargs`` to the construction and to the parse, so a keyword only ``read``
    declares still travels through ``make``.
 
    Shapes a signature cannot express are declared on the class instead, via
-   :attr:`ProtocolBase.__keywords__
+   :attr:`Protocol.__keywords__
    <pcapkit.protocols.protocol.ProtocolBase.__keywords__>`:
 
    .. code-block:: python
@@ -271,7 +271,7 @@ The following code snippet shows how to create a new protocol class:
    subclass of a dispatcher is checked normally. Prefer a declared parameter to
    either: it is also what documents the keyword to your callers.
 
-   Parsing is unaffected. :meth:`ProtocolBase.from_data
+   Parsing is unaffected. :meth:`Protocol.from_data
    <pcapkit.protocols.protocol.ProtocolBase.from_data>` checks the keywords its
    caller passes just as strictly, raising
    :exc:`~pcapkit.utilities.exceptions.UnsupportedCall`, but only warns with
@@ -281,7 +281,7 @@ The following code snippet shows how to create a new protocol class:
 
    .. warning::
 
-      The check lives in :meth:`ProtocolBase.__init__
+      The check lives in :meth:`Protocol.__init__
       <pcapkit.protocols.protocol.ProtocolBase.__init__>`, where every producer's
       keywords converge, so it covers ``SomeProtocol(...)`` and the ``pack`` it
       leads to -- but **not** a direct ``SomeProtocol.make(...)`` call, which still

docs/source/pcapkit/protocols/internet/ipv6_ext.rst

@@ -141,7 +141,7 @@ This class is reached in these ways:
    ``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all
    have dedicated classes. When one of *those* raises,
    :func:`~pcapkit.corekit.decorators.beholder`
-   (:meth:`ProtocolBase._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
+   (:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
    would substitute plain :class:`~pcapkit.protocols.misc.raw.Raw`, which loses
    ``next`` and crashes the walk as in path 1.
    :meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>` catches

docs/source/pcapkit/utilities/chardet.rst

@@ -7,7 +7,7 @@ Character Set Detection
 turning the bytes of a text field into a :obj:`str`. It is shared by
 :meth:`StringField.post_process
 <pcapkit.corekit.fields.strings.StringField.post_process>` and
-:meth:`ProtocolBase.decode <pcapkit.protocols.protocol.Protocol.decode>`,
+:meth:`Protocol.decode <pcapkit.protocols.protocol.Protocol.decode>`,
 which is why it lives here rather than beside either of them.
 
 .. autofunction:: pcapkit.utilities.chardet.detect

pcapkit/corekit/decorators.py

@@ -56,7 +56,7 @@
 
 #: contextvars.ContextVar[bool]: Whether a call :func:`beholder` wraps is under
 #: way, so that an :exc:`Exception` raised inside it ends with the layer that
-#: raised replaced; see :meth:`ProtocolBase._parse_next_layer
+#: raised replaced; see :meth:`Protocol._parse_next_layer
 #: <pcapkit.protocols.protocol.ProtocolBase._parse_next_layer>` (:issue:`2308`).
 _beholding = contextvars.ContextVar('_beholding', default=False)
 
@@ -116,7 +116,7 @@ def beholder(
     :class:`~pcapkit.protocols.misc.null.NoPayload`, if the error is an
     end-of-file :exc:`~pcapkit.utilities.exceptions.StructError`.
 
-    When :meth:`ProtocolBase._parse_next_layer
+    When :meth:`Protocol._parse_next_layer
     <pcapkit.protocols.protocol.ProtocolBase._parse_next_layer>` held the
     warnings of the layer that raised, they are dropped with it: they describe a
     layer the result does not have, and the replacement's ``error`` reports the

pcapkit/corekit/fields/numbers.py

@@ -730,7 +730,7 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'Stdli
             the registry with ``aenum.extend_enum``, for two reasons: a
             capture carrying many distinct unassigned codes would otherwise grow
             a process-global registry without bound, which is the growth
-            :meth:`ProtocolBase._lookup_registry
+            :meth:`Protocol._lookup_registry
             <pcapkit.protocols.protocol.ProtocolBase._lookup_registry>` exists
             to avoid; and a stdlib :class:`enum.IntEnum` registry is then
             handled exactly like an ``aenum.IntEnum`` one.

pcapkit/corekit/module.py

@@ -60,7 +60,7 @@ def klass(self) -> 'Type[_T]':
             The module is read from :data:`sys.modules` first, and
             :func:`importlib.import_module` is entered only when it is not
             loaded yet. That matters because this property is on a *per-frame*
-            dispatch path: :meth:`ProtocolBase._lookup_next_layer
+            dispatch path: :meth:`Protocol._lookup_next_layer
             <pcapkit.protocols.protocol.ProtocolBase._lookup_next_layer>`
             deliberately writes no resolved class back, so every next layer
             lookup resolves its descriptor again -- the one registered for the

pcapkit/corekit/sentinels.py

@@ -571,7 +571,7 @@ def __bool__(self) -> 'Literal[False]':
 #: own ``__keywords__`` out of its :attr:`~object.__dict__`, where
 #: :obj:`None` is itself a meaningful value -- the opt-out that says the
 #: class cannot enumerate its keywords, cf.
-#: :attr:`ProtocolBase.__keywords__
+#: :attr:`Protocol.__keywords__
 #: <pcapkit.protocols.protocol.ProtocolBase.__keywords__>`. Never leaves
 #: :mod:`pcapkit.protocols.protocol`, which imports it from here for exactly
 #: that one read. Private by documentation rather than by a

pcapkit/foundation/engines/dpkt.py

@@ -551,7 +551,7 @@ def read_frame(self) -> 'DPKTPacket':
         try:
             packet = protocol(pkt)  # type: DPKTPacket
         except Exception as exc:  # pylint: disable=broad-except
-            # NOTE: Caught broadly, as :meth:`ProtocolBase.analyze
+            # NOTE: Caught broadly, as :meth:`Protocol.analyze
             # <pcapkit.protocols.protocol.ProtocolBase.analyze>` does: dpkt raises
             # more than its own ``UnpackError`` while parsing -- dpkt 1.9.8 reads
             # ``frag_off`` from whatever header follows an IPv6 Fragment header,

pcapkit/protocols/application/application.py

@@ -121,7 +121,7 @@ def from_data(cls, data: '_PT | dict[str, Any]', **kwargs: 'Any') -> 'Self':
 
         Args:
             data: Protocol data.
-            **kwargs: Construction keywords, as for :meth:`ProtocolBase.from_data
+            **kwargs: Construction keywords, as for :meth:`Protocol.from_data
                 <pcapkit.protocols.protocol.ProtocolBase.from_data>`.
 
         Returns:

pcapkit/protocols/application/http.py

@@ -404,7 +404,7 @@ def from_data(cls, data: '_PT | dict[str, Any]', **kwargs: 'Any') -> 'Self':
                 into the versioned data model its keys belong to -- ``receipt``
                 is HTTP/1.*'s and ``sid`` HTTP/2's -- since this class's own data
                 model carries no version.
-            **kwargs: As :meth:`ProtocolBase.from_data
+            **kwargs: As :meth:`Protocol.from_data
                 <pcapkit.protocols.protocol.ProtocolBase.from_data>`.
 
         Returns: