docs(contributing): record the documentation house rules (#719)

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change
• Added a changelog entry — N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• docs — documentation only

---

Description of your pull request and other information

conventions/ held five pages, all about code or process, so every documentation
ruling from #719 lived only in that thread. New conventions/documentation.rst
records them; conventions/index.rst introduces and lists it, and
test_conventions_doc_claims.py's ANCHORS gains the page so its anchor and toctree
position are pinned like the other five.

Rules recorded, with provenance: heading case and shape (#719, and #971 for the
62-heading sweep, the finite-verb test, and a heading having to describe its section);
the rename traps — re-measure the underline, sweep the whole repository not just
docs/, derive old headings from the pre-change file rather than the diff (all #971;
#934 for a dead reference staying green); Mermaid for flows (#719, bounded by his
no-duplicate-information condition; style model re-derived as 12 directives on 11
pages); toctree captions (#972, #975); paraphrase, never quote (#719, #949/#951);
accuracy (#719, #657's six-form method, #911 and 68fbccd90 as worked quantifier
defects, plus the test-pinned #NNN-matches-its-URL rule); resolvable .. module::
targets (#719); reST inside docs/source/, Markdown outside (#719, 2026-09-26).

Left out: ".rst, never .md" — #719 explicitly corrected that, so the page
carries the corrected split instead. Also left out: #nnn never GH-nnn, for which
no ruling exists and which the tree contradicts (four live GH-nnn comments in
pcapkit/). Added: the finite-verb test, heading-describes-section, no inline
.. contents::, and that a measured Sphinx setting records its measurement beside it.

Verified against its own rules: 9 headings, all Title Case, none a sentence, every
underline exact; all 8 :ref:, 3 :doc: and 4 :mod: references resolve in the built
HTML; no duplicate-label warning for .. _documentation:. Sphinx build succeeds with
61 warnings, byte-identical to a baseline build of main. 67 tests across the five
modules that read these pages: OK (skipped=1) under both pytest and plain
unittest.

[JarryShaw]

NEEDS CHANGES at 4cd8dc6fe — sonnet cross-review, round 1. One real defect, and it
is the one I most wanted found: the page broke its own accuracy rule. Fixed at
d9cad98d4.

The Toctree Captions section gave a worked grep -rl 'Subpackages' ... | wc -l # one.
But the page's own prose names Subpackages at :137, so once the page is built that
command returns 2, not 1 — the reviewer measured it: main baseline 600 pages / 1
hit, PR branch 601 / 2, the extra being documentation.html itself. A reader
re-running the example on a page about re-deriving counts would get the wrong number.
Both greps now --exclude='documentation.html', with the reason stated in the prose.

Everything else it checked came back exact, re-derived rather than taken from the
PR: 9 headings all Title Case, no finite verb, underlines matching to the character, ≤88
columns; 12 Mermaid directives across 11 pages; 486 .. module:: targets with 0
dangling; 519 .py under pcapkit/ with 33 undocumented, all under NotImplemented/.
That last settles the 486/33-versus-487/32 drift in favour of the page.

Provenance held on all five flagged citations — the heading ruling at 14:57:42Z, the
Mermaid ruling at 05:18/05:22Z, the caption facts against #972's and #975's own bodies,
the removal handling at 15:14:36Z, and the .rst/.md correction at 2026-09-26T13:37Z.
It also confirmed the test edit does not weaken anything: dropping 'documentation'
from a copy of ANCHORS makes the equality check fail, so the toctree test still bites.

One rule it flagged as my author's extrapolation, which I am keeping as written:
that a measured Sphinx setting records its measurement beside it in conf.py. It is
generalised from the single toc_object_entries precedent — but the page's sentence
already names that instance rather than asserting a universal, which is the honest
framing. Leaving it.

Build: 61 warnings both ways, sorted sets byte-identical, no duplicate-label or orphan
warnings. Re-verified after my fix: 0 underline mismatches, 0 lines over 88, Ran 38 tests ... OK (skipped=1).

[JarryShaw]

NEEDS CHANGES at d9cad98d4 — sonnet cross-review, round 2. Fixed at 87702d3f8.

It found the same defect a second time, in the Mermaid block, and worse. The page
writes mermaid:: three times in its own prose (:111, :112, :114), so its own
worked example inflates by three once the page joins the tree. Re-derived in a scratch
worktree at the PR head, running the commands exactly as the page wrote them:

as written:                 -rn 15   -rl 12      <- the page claimed 12 and 11
--exclude='documentation.rst':  12       11      <- correct, and matches main

Round 1's --exclude went on the toctree block only. Both worked greps now carry it,
and the prose above each says why so nobody prunes the flag as noise. Checked the
third code-block: the .. module:: sweep is anchored to ^\.\. +(py:)?(module|…)
and the page only ever writes that inline, so it matches itself 0 times — safe.

Taken on its push-back about the measured-setting rule. Where a Sphinx setting was decided by measurement, … reads as a general convention, and it has exactly one
grounding instance and no ruling behind it. Rewritten to describe toc_object_entries
as the single precedent it is.

One thing it did not raise, fixed anyway: four sentences used gendered pronouns for
the owner. Now neutral. A fifth, pre-existing on conventions/registry-protocol.rst:274,
goes to the #719 final sweep rather than widening this PR.

Verified after the fix: 12/11 from the page's own commands; 0 lines over 88; 9 headings,
all Title Case, underlines exact; build 61 warnings, byte-identical set to the main
baseline, no duplicate-label or orphan; 600 of 601 pages carry API Reference and
exactly 1 carries Subpackages, as the page states; 37 passed, 1 skipped, 140 subtests.

[JarryShaw]

NEEDS CHANGES at 87702d3f8 — opus cross-review, round 3. Fixed at 949bab55f.
A different model, and it found two defects neither earlier round reached.

1. The Mermaid labelling rule was half false. "Node labels are quoted" sat two
sentences after "the style model is the set already in the tree" — and the six LR
exemplars quote no node label. Re-derived per block: the six TD graphs quote every
label; the six LR ones use bare A{{Meta}}, B(Base), C([user customisation ...])
and subgraph name [Title], spending their quotes on click targets instead. Rule now
split by direction. (The reviewer read the LR blocks as quote-free; they do contain
quotes, just not in labels — checked before relaying.)

2. The page claimed a safety net that does not cover it. "A number written onto one
of these pages is pinned" — but test_conventions_doc_claims.py pins figures only for
the two pages that have such a test. This page's own numbers are pinned by nothing; its
ANCHORS entry fixes existence, anchor and toctree position only. Narrowed, and the page
now says which numbers are load-bearing.

3. A claim the reviewer could only flag as suspect, measured. The page said the
NotImplemented modules "are not shipped", citing MANIFEST.in. Built both artifacts:

sdist pypcapkit-1.5.0b8.tar.gz   33 .py under NotImplemented/   -> they DO ship
wheel pypcapkit-1.5.0b8-py3...   33 entries                     -> and here too
import pcapkit.protocols.application.NotImplemented.bgp          -> succeeds
find_packages 73 / find_namespace_packages 77                    -> not a package

exclude pcapkit/protocols/*/NotImplemented cannot reach files inside the directory,
and global-include *.py above it does. The exception is a deliberate choice, not a
packaging consequence; corrected to say so.

4. The third worked grep was latent, now not. It self-matched 0 times only because
the page writes .. module:: inline, never at column 0. It carries the exclusion too.

Verified after: all three greps return the stated figures; HTML pair 600 of 601 and
exactly 1; 486 module targets, 0 dangling; 9 headings Title Case, underlines exact; max
line 88; build 61 warnings, set byte-identical to the main baseline, none naming the
page; 37 passed, 1 skipped, 140 subtests.

[JarryShaw]

NEEDS CHANGES at 949bab55f — sonnet cross-review, round 4. Fixed at 34bbdeff0.

The defect was in round 3's own fix, and it was mine. I had rewritten the Mermaid rule
as "every node label in the six TD graphs is quoted, and none in the six LR ones is".
pcapkit/protocols/index.rst:75 quotes two: h1["HTTP/1.*"] and h2["HTTP/2"].

Worse than a miss — I had the evidence and talked myself out of it. My round-3
measurement printed quoted=2 for that one file. I checked whether LR quotes were really
click targets by reading traceflow/index.rst, found they were, and generalised from
that one file to all six. Re-derived per block, node labels only, click lines excluded:

TD  6 graphs   every label quoted
LR  5 graphs   zero quoted
LR  protocols/index.rst   2 quoted: HTTP/1.*  HTTP/2

That is the fourth instance of the one class every round has found, and the page's own
Accuracy section is the rule I broke: treat "every/none" as a claim about members and check
them individually. A direction-based split was never the real rule. The page now states the
reason instead — quote a label whose text Mermaid would otherwise parse — notes that it
falls close to the TD/LR line without following it, and names the two exceptions and
why (/ and *).

Round 4 confirmed everything else by its own measurement rather than from the diff: 12
directives / 11 pages; 486 .. module:: targets, 0 dangling; the full sdist and wheel
rebuild with all 33 NotImplemented modules present in both and all 33 importable;
find_packages → 73; HTML 600 of 601 and exactly 1; both builds 61 warnings with an empty
diff between the sorted sets; the ANCHORS entry bites when removed; 9 headings Title Case,
underlines exact, max line 88. It also checked #971's and #972's figures against those PRs'
own bodies rather than this one's.

Four UNVERIFIED items, all historical rather than about the tree as it stands: the ~thirty
corrupted #NNN links, #934's sixteen, the pre-#911 sentinel export state, and the exact
line numbers of #971's five stale references.

Verified after my fix: 0 lines over 88, max exactly 88; 0 underline mismatches; build 61
warnings, 0 duplicate-label, 0 orphan, 0 naming the page; HTML pair 600 of 601 and exactly
1; 37 passed, 1 skipped, 140 subtests.

[JarryShaw]

NEEDS CHANGES at 34bbdeff0 — opus cross-review, round 5. Fixed at 8fb086a01.
Five rounds, eight defects, one class every time, and three of the last four were in
prose written to fix the round before it.

1. "every label in the six TD graphs is quoted" — true of node labels, false of edge
labels. 23 bare edge labels across three of the six, re-derived per block:

pep.rst:863        2   |workflow_run: completed| x2
workflows.rst:102  14  |02:00| |04:00| |06:00| |10:00| |uses: gate-only| x4 ...
workflows.rst:250  7   |if: false| |needs| x6

Several carry a colon, so the page's own stated reason would have quoted them and
Mermaid accepts them bare regardless. Scoped the rule to node labels and said plainly that
edge labels follow no rule, naming two of the bare ones.

2. The figure-pinning sentence named two pages; there are three. registry-protocol
is pinned harder than either — :426 the outside-the-hierarchy count, :462 both
halves of "landed for 24 of the 24", :523 a table of regex/value pairs, :1114 the
helper count. Its "every other figure is pinned by nothing" was therefore false. The
contradicting fact was in the module's own docstring at :26, which the page cites.

3. C([user customisation ...]) is the wrong node id — it is D in all six LR
graphs (D/E in dumpkit); C is C(Protocol). Corrected.

One of my own, caught by the page's own rule while fixing the above: my edit left
:235 at 92 columns against the 88 the page sets for itself. Rewrapped; longest line is
now exactly 88.

Round 5 re-derived and confirmed: 12 directives on 11 pages with the exclusion and 15/12
without, so it is load-bearing; 486 .. module:: targets, 0 dangling; 4 NotImplemented
dirs, 33 .py, no __init__.py, find_packages → 73; exactly 4 captioned toctrees;
.. contents:: commented at index.rst:18 since 0209e04965; 9 headings, underlines
exact. It also stress-tested the "every importable shipped module is documented" rule
and found a 34th undocumented module by module:: alone — pcapkit.foundation.reassembly.tcp
— which does have a page, via currentmodule + autoclass. Worth knowing that a sweep
keyed on module:: alone flags it; the rule itself holds.

Every provenance citation checked against the real sources and all hold, including the
function-word list left standing on 2026-09-29 and #971's one-vs-five stale references.

Its UNVERIFIED list is the build comparison and the sdist/wheel rebuild, both of which
round 4 did measure, plus four historical claims.

[JarryShaw]

GOOD TO GO at 8fb086a01 — sonnet cross-review, round 6, first clean round after five. But
that is not the current head: 3e7340da2 landed the PR-citation conversion while the review
was running, so the verdict does not cover the newest prose. Round 7 is running on it.

Round 6 re-derived every quantified claim rather than reading the diff. Confirmed: 12 directives
on 11 pages; 6 TD + 6 LR parsed programmatically, every TD node label quoted and the only
quoted LR node labels anywhere being h1["HTTP/1.*"] and h2["HTTP/2"], by exhaustive scan;
both cited bare edge labels bare in source, and a quoted edge label elsewhere, so "edge labels
follow no rule" holds; 33 .py across exactly 4 dirs with no __init__.py, find_packages → 73
under setuptools 84.0.0, and a real sdist and wheel built with all 33 in both and four imported as
_NamespacePath submodules; 486 .. module:: targets, 0 dangling; 9 headings, underlines exact,
max width exactly 88, zero gendered pronouns.

It closed round 5's UNVERIFIED build comparison, which is the useful part: both the PR tree and
main at 3f363fba4 build with exactly 61 warnings, and after normalising the path prefix the two
sets diff clean — byte-identical, not merely equal counts. No duplicate-label or orphan in either,
none naming the new page. Since Sphinx warns on an unresolvable :ref:/:doc: regardless of
nitpicky, that also establishes every cross-reference the page adds resolves.

One divergence I checked rather than relayed. It measured API Reference on 134 of 134 pages
where I measured 600 of 601 — a build-size difference between our two trees, not a defect. The page
states the claim relationally (# every other page, # exactly one) and never gives an absolute,
so both measurements confirm it, and both got exactly 1 for Subpackages. Stating it relationally
is why the divergence costs nothing; an absolute would have been wrong in one of the two builds.

UNVERIFIED by it: the test run, and the historical sweep figures round 5 had already checked
against the source issues.