docs(docs): fifth whole-repo pass over the non-API docs, with issue/PR roles (#1103)

docs/source/contributing/conventions/documentation.rst

@@ -314,6 +314,17 @@ Format and Mechanics
    :file:`MANIFEST.in` does not reach Markdown, so the READMEs under :file:`examples/`
    ship through ``recursive-include examples *.md``, and any other Markdown file
    ships only if setuptools or an ``include`` line adds it.
+*  **Cite an issue or a pull request by role wherever Sphinx renders the text.** In an
+   ``.rst`` page, a docstring or a ``#:`` doc-comment an issue is ``:issue:`NNN``` and
+   a pull request ``:pr:`NNN```, by what the number is rather than what a URL says: a
+   bare ``#NNN`` there renders as plain text, and a hand-written link to the tracker
+   hides which of the two it names. A plain ``#`` comment, a workflow's YAML comment,
+   :file:`tests/` and any other file nothing renders keep ``#NNN``, which GitHub links
+   itself. A link into another repository or to a Discussion keeps its URL, and
+   ``GH-NNN`` is a deliberate issue form. Ruled on :issue:`1103`;
+   :file:`tests/project/test_docs_issue_pr_roles_1103_unit.py` fails on a bare number
+   or a hand-written link in rendered text, and
+   :file:`tests/project/test_issue_refs_in_comments.py` on a role in a plain comment.
 *  **Prose names the real defining module, not a re-export.** One strand of the
    consistency sweep on :doc:`the roadmap </contributing/pep>`. The sentinels are the
    worked example: every one is defined in :mod:`pcapkit.corekit.sentinels`, and

docs/source/contributing/conventions/process.rst

@@ -65,7 +65,7 @@ back to the default engine rather than raising when a requested engine is absent
    toolchain. ``dev`` is defined by what the toolchain must be able to *see*, and the
    workflows that need full resolution install ``.[all,dev]``. Do not add
    ``pypcap``/``pcap-ct`` to it to silence a lint finding; :file:`.github/workflows/lint.yml`
-   carries a tracked ``import-error`` count that is deliberate rather than accidental.
+   expects pylint's ``import-error`` for them, deliberately rather than by accident.
 
 .. note::
 
@@ -88,9 +88,9 @@ detail of what actually changed in that version bump. Ruled on
 
 Two different things get confused here, so they are named apart:
 
-*  **A pull request's commits.** The shared changelog for the 1.5.0 cycle is a
+*  **A pull request's commits.** The shared changelog for the 1.5.0 cycle was a
    long-lived pull request of its own, carrying roughly one commit per code pull
-   request, deliberately unsquashed so that what is and is not accounted for stays
+   request, and merged unsquashed so that what is and is not accounted for stays
    readable in its log. That is a property of *the pull request*, and it is not what
    the ruling is about.
 *  **A changelog file's entries.** :file:`docs/source/changelog/1.5.0.rst` groups its
@@ -142,9 +142,9 @@ belongs to none. The map is one-to-one with the package list below -- every pack
    section wants that module's changes; the same prose appearing twice reads as two
    separate changes. Raised originally on :issue:`918`.
 
-   The restructure itself belongs to the shared changelog's own pull request, which
-   owns the file and merges last; doing it earlier would conflict with every open
-   change that touches an entry.
+   The restructure itself was done on the shared changelog's own pull request, which
+   owned the file and merged last; doing it earlier would have conflicted with every
+   open change that touched an entry.
 
 Issue and Pull Request Labels
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/contributing/pep.rst

@@ -360,7 +360,7 @@ PCAPNG Support
 **Done.** The builtin default engine parses PCAP-NG files;
 :class:`~pcapkit.protocols.misc.pcapng.PCAPNG` implements the format, with its
 block and option enumerations under :doc:`/pcapkit/const/pcapng`. This closes
-`#35 <https://github.com/JarryShaw/PyPCAPKit/issues/35>`__.
+:issue:`35`.
 
 Maybe Even Faster?
 ------------------
@@ -506,8 +506,8 @@ both of the following are worth knowing before reaching for them:
   ``import pcapfile`` still succeeds on 3.12+, the modules the engine
   actually needs raise :exc:`ModuleNotFoundError`. Upstream ``master`` (0.12.1,
   unreleased) has fixed this, and that is what the engine was verified against.
-  The extra therefore installs a version that only works on Python 3.10 and
-  3.11 until 0.12.1 is published.
+  The extra therefore installs a version that does not work on Python 3.12 or
+  newer until 0.12.1 is published.
 * **pypcap** -- the 1.3.0 sdist (the only distribution; there has been no wheel
   since Python 2.7) ships a ``pcap.c`` pre-generated by Cython 0.29.32 and
   compiles it verbatim -- its :file:`setup.py` never invokes Cython. That
@@ -1116,7 +1116,7 @@ library gets swept deliberately, in strands:
 * **Packet formats against the specifications.** The most valuable strand, and
   the one with the clearest evidence behind it: reading the RFC field-by-field
   against the schema is what produced
-  `#472 <https://github.com/JarryShaw/PyPCAPKit/issues/472>`__ — HIP
+  :issue:`472` — HIP
   parameters sizing their list entries at one octet where :rfc:`5770` §5.4 and
   :rfc:`7402` §5.1.2 specify sixteen bits — and the same method then *cleared*
   the further
@@ -1129,13 +1129,13 @@ library gets swept deliberately, in strands:
   This strand has the sharpest evidence of them all, because duplication here has
   already *caused* defects rather than merely offended tidiness:
 
-  - `#487 <https://github.com/JarryShaw/PyPCAPKit/issues/487>`__ existed because
+  - :issue:`487` existed because
     :meth:`IPv6_Route.make() <pcapkit.protocols.internet.ipv6_route.IPv6_Route.make>`
     computed ``Hdr Ext Len`` in **separate** branches with different wrong units, and the
     read side computed the inverse elsewhere with yet another. The fix was not new
     arithmetic but one helper per direction, each documenting the :rfc:`8200#section-4.4`
     unit and saying what its counterpart is.
-  - `#483 <https://github.com/JarryShaw/PyPCAPKit/issues/483>`__ was the scapy
+  - :issue:`483` was the scapy
     toolkit adapter passing a fragment offset unscaled where every sibling
     adapter scaled it. Every adapter restates the same field mapping, so a
     convention that holds in all but one is invisible until a capture is