Skip to content

Commit 3dcd2f3

Browse files
committed
docs(docs): fifth whole-repo pass over the non-API docs, with issue/PR roles (#1103)
- Cite issues and pull requests by :issue:/:pr: in rendered text: the hand-written GitHub links in workflows.rst, releasing.rst and pep.rst, the bare #NNN in workflows.rst, and the #NNN in pcapkit docstrings and #: comments. #2050, linked as an issue, is a pull request. - Add tests/project/test_docs_issue_pr_roles_1103_unit.py, which fails on a hand-written link or bare #NNN in .rst pages, docstrings and #: comments; its allowlist holds only the references other tests pin. - Record the rule on the documentation conventions page. - Name the external action functions releasing.rst and workflows.rst cited by line, where no test pins the line. - Fix stale claims: the shared changelog pull request has merged, the Windows leg runs leg_summary.py and pip_install.py, Lint expects pylint's import-error rather than tracking a count, pypcapfile fails from 3.12 up rather than working only on 3.10 and 3.11, cryptography in the all extra is no pure-Python wheel; drop "today", "this change" and "current". Docs build: no warnings, and the same 116 under -n as origin/main.
1 parent 4c3d301 commit 3dcd2f3

19 files changed

Lines changed: 493 additions & 183 deletions

File tree

‎docs/source/contributing/conventions/documentation.rst‎

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

‎docs/source/contributing/conventions/process.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ back to the default engine rather than raising when a requested engine is absent
6565
toolchain. ``dev`` is defined by what the toolchain must be able to *see*, and the
6666
workflows that need full resolution install ``.[all,dev]``. Do not add
6767
``pypcap``/``pcap-ct`` to it to silence a lint finding; :file:`.github/workflows/lint.yml`
68-
carries a tracked ``import-error`` count that is deliberate rather than accidental.
68+
expects pylint's ``import-error`` for them, deliberately rather than by accident.
6969

7070
.. note::
7171

@@ -88,9 +88,9 @@ detail of what actually changed in that version bump. Ruled on
8888

8989
Two different things get confused here, so they are named apart:
9090

91-
* **A pull request's commits.** The shared changelog for the 1.5.0 cycle is a
91+
* **A pull request's commits.** The shared changelog for the 1.5.0 cycle was a
9292
long-lived pull request of its own, carrying roughly one commit per code pull
93-
request, deliberately unsquashed so that what is and is not accounted for stays
93+
request, and merged unsquashed so that what is and is not accounted for stays
9494
readable in its log. That is a property of *the pull request*, and it is not what
9595
the ruling is about.
9696
* **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
142142
section wants that module's changes; the same prose appearing twice reads as two
143143
separate changes. Raised originally on :issue:`918`.
144144

145-
The restructure itself belongs to the shared changelog's own pull request, which
146-
owns the file and merges last; doing it earlier would conflict with every open
147-
change that touches an entry.
145+
The restructure itself was done on the shared changelog's own pull request, which
146+
owned the file and merged last; doing it earlier would have conflicted with every
147+
open change that touched an entry.
148148

149149
Issue and Pull Request Labels
150150
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎docs/source/contributing/pep.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -360,7 +360,7 @@ PCAPNG Support
360360
**Done.** The builtin default engine parses PCAP-NG files;
361361
:class:`~pcapkit.protocols.misc.pcapng.PCAPNG` implements the format, with its
362362
block and option enumerations under :doc:`/pcapkit/const/pcapng`. This closes
363-
`#35 <https://github.com/JarryShaw/PyPCAPKit/issues/35>`__.
363+
:issue:`35`.
364364

365365
Maybe Even Faster?
366366
------------------
@@ -506,8 +506,8 @@ both of the following are worth knowing before reaching for them:
506506
``import pcapfile`` still succeeds on 3.12+, the modules the engine
507507
actually needs raise :exc:`ModuleNotFoundError`. Upstream ``master`` (0.12.1,
508508
unreleased) has fixed this, and that is what the engine was verified against.
509-
The extra therefore installs a version that only works on Python 3.10 and
510-
3.11 until 0.12.1 is published.
509+
The extra therefore installs a version that does not work on Python 3.12 or
510+
newer until 0.12.1 is published.
511511
* **pypcap** -- the 1.3.0 sdist (the only distribution; there has been no wheel
512512
since Python 2.7) ships a ``pcap.c`` pre-generated by Cython 0.29.32 and
513513
compiles it verbatim -- its :file:`setup.py` never invokes Cython. That
@@ -1116,7 +1116,7 @@ library gets swept deliberately, in strands:
11161116
* **Packet formats against the specifications.** The most valuable strand, and
11171117
the one with the clearest evidence behind it: reading the RFC field-by-field
11181118
against the schema is what produced
1119-
`#472 <https://github.com/JarryShaw/PyPCAPKit/issues/472>`__ — HIP
1119+
:issue:`472` — HIP
11201120
parameters sizing their list entries at one octet where :rfc:`5770` §5.4 and
11211121
:rfc:`7402` §5.1.2 specify sixteen bits — and the same method then *cleared*
11221122
the further
@@ -1129,13 +1129,13 @@ library gets swept deliberately, in strands:
11291129
This strand has the sharpest evidence of them all, because duplication here has
11301130
already *caused* defects rather than merely offended tidiness:
11311131

1132-
- `#487 <https://github.com/JarryShaw/PyPCAPKit/issues/487>`__ existed because
1132+
- :issue:`487` existed because
11331133
:meth:`IPv6_Route.make() <pcapkit.protocols.internet.ipv6_route.IPv6_Route.make>`
11341134
computed ``Hdr Ext Len`` in **separate** branches with different wrong units, and the
11351135
read side computed the inverse elsewhere with yet another. The fix was not new
11361136
arithmetic but one helper per direction, each documenting the :rfc:`8200#section-4.4`
11371137
unit and saying what its counterpart is.
1138-
- `#483 <https://github.com/JarryShaw/PyPCAPKit/issues/483>`__ was the scapy
1138+
- :issue:`483` was the scapy
11391139
toolkit adapter passing a fragment offset unscaled where every sibling
11401140
adapter scaled it. Every adapter restates the same field mapping, so a
11411141
convention that holds in all but one is invisible until a capture is

0 commit comments

Comments
 (0)