docs(contributing): split conventions.rst into one file per anchor (#918)

[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
• Changelog: N/A -- changelog 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

Part 2 of #918 (three parts total; part 1 is the harvest sweep, part 3 is a
standing obligation). Splits the 966-line
docs/source/contributing/conventions.rst -- four unrelated design rulings on
one page -- into docs/source/contributing/conventions/, one file per
.. _label: anchor (mint-criterion, sentinel-convention,
registry-protocol, extension-header-subclassing), plus index.rst
carrying the toctree and the .. important:: preamble. Every split file is
byte-identical to its slice of the original.

Fixes the one :doc: reference that breaks on a move (docs/source/index.rst's
toctree entry) and the file-path assumptions in
tests/corekit/test_sentinel_exports_unit.py and
tests/project/test_conventions_doc_claims.py, which previously sliced the
single page between two anchors -- exactly what #930 flagged as this split's
blocker. :ref: targets needed no changes; Sphinx anchors are global.

Verified with a nitpicky sphinx-build: warning set is unchanged (1287,
byte-identical to 9ea0d6a5a once ambiguous-xref candidate ordering is
normalised) -- no new undefined label or unknown document warnings.

[JarryShaw]

Verified at 6ed02cde2, and the central claim holds: the split is provably lossless. review: pending while a Fable cross-review runs (author was Sonnet), so not a good-to-go yet.

Content preservation, measured rather than inspected. Reconstructing the original by concatenating index.rst's first 24 lines with the four pages in order:

reconstructed: 966 lines   original: 966 lines
md5 both:      e0f944625eaca4d8f2d46e192470b113
diff -q: silent

So no prose was altered. One .. _label: anchor per file, none leaked, and the only added content is the 7-line toctree.

Reference integrity, from my own nitpicky build (python -m sphinx -n -b html -j 4, PYTHONPATH exported and the documented root asserted to be the worktree, which is the trap that would have invalidated the result):

• undefined label / unknown document: 0
• warnings mentioning conventions at all: 0
• duplicate label / toctree / document isn't included: 0 — these are precisely the categories a file split can introduce

The residual 1289 are the pre-existing noise floor, all in unrelated categories (1202 py reference targets, 36 ambiguous cross-references, 14 c, 10 envvar, 7 duplicate object descriptions).

It caught the functional break I had flagged as the real risk. tests/corekit/test_sentinel_exports_unit.py's _sentinel_section() sliced between .. _sentinel-convention: and .. _registry-protocol: — which cannot work once each anchor owns its file. Rewritten to read the page whole. Both rewritten suites pass on the branch (39 tests, OK, 1 skipped) and fail hard with the old single-file layout dropped back in.

Two small discrepancies with the author's report, neither material, both stated rather than smoothed over. It reported the baseline failure count as 21+3 for one suite and 4 for the other (25 failures, 3 errors); running them together I measured 24 failures, 3 errors. And it reported 1287 warnings where my count is 1289 — different counting expressions, not a different build. I did not run the baseline build, so I cannot confirm its "zero-line warning-set diff" literally; what I have instead is targeted and stronger for the question that matters, namely that every split-specific warning category is empty.

[JarryShaw]

NEEDS CHANGES at 6ed02cde2 — Fable cross-review (author was Sonnet) returned GOOD TO GO with one prose nit. Checking it myself I think it is slightly broader than reported, and it lands on the one sentence that most needs to be right, so I am holding the PR for it rather than waving it through.

The .. important:: preamble moved into index.rst unchanged, which is exactly why it is now partly false — a byte-identical move guarantees the words survived, not that they are still true:

• :6 "This page records design rulings for pcapkit" — the index records none of them; the four children do.
• :19-20 "it is written onto this page in the same change that implements it" — this is the important one. It is the standing obligation docs: harvest every settled design ruling into the convention docs, and split them per category #918 Part 3 exists to record, and as written it now instructs a contributor to put a new ruling on the hub rather than on the page that covers it.
• :11-13 "the page was titled Registry Conventions … until docs: harvest every settled design ruling into the convention docs, and split them per category #918 widened it" — docs: harvest every settled design ruling into the convention docs, and split them per category #918 also split it, which the sentence omits, and "the page" is now five.

Round 2 rewrites that paragraph to be true of an index while keeping the same voice, both owner quotes, and the .. important:: directive. The four child pages stay untouched — they are verified byte-identical to their slices of the original and I want that property to survive the round.

Everything else verified, independently of the author's report. Reconstruction: 966 lines, md5 e0f944625eaca4d8f2d46e192470b113, diff silent. My own nitpicky build: exit 0, zero undefined label/unknown document, zero warnings mentioning conventions, zero duplicate label/toctree/document isn't included. Test inventory base→PR: exactly one method removed (test_the_sentinel_slice_markers_stay_in_one_file_and_in_order, obsolete by design since it pinned the pre-split slice) against four added — so no coverage was traded away for structural checks, which was the failure mode I had the review hunting for.

The review also mutation-tested all five new ConventionAnchorTests and got each to fail on its own violation, and checked every one of the nine retargeted prose citations names the correct sibling page rather than merely a new one. It confirmed the R0801 1→2 reading is accurate and the AH/ESP precedent real, while noting the precedent is weaker than the author's argument implies — that hit is incidental shared docstring prose, not a copied helper. Agreed on leaving it; if a third copy of _toctree_entries appears, it belongs in tests/_support.py.

One prediction of mine it disproved: I had briefed it that cross-file prose breakage was the most likely defect. It found the split boundaries coincide almost exactly with the prose's own referential boundaries — every directional phrase in the four child pages points within its own file. The index preamble is the sole residue.

[JarryShaw]

GOOD TO GO at 9f86eba66 — round 2 fixes all three false sentences, and the property I most wanted preserved survived intact.

The four child pages are still byte-identical to their exact slices of 9ea0d6a5a's original, re-derived by me rather than taken from the report: mint-criterion.rst e87cc094, sentinel-convention.rst b683cdaa, registry-protocol.rst c60afda7, extension-header-subclassing.rst 34d98905. Round 2's delta touches only index.rst (26 lines) and the test file (+34), so the lossless split is untouched by the prose fix.

The three corrections:

• "This page records" → "The pages below record"
• "widened it" → "widened it, then split it" — the history now names both
• "written onto this page" → "written onto the page that covers it" — the load-bearing one

The author chose to pin this with a test, and rejected the broader version I floated, correctly. My suggestion was to assert that no page says "this page" about a sibling's content; it pointed out the four child pages legitimately say "this page" about their own, so that check needs semantic judgement about where a ruling ought to live — the very thing a human reviewer just did — and would be false-positive-prone. It scoped the ban to index.rst alone, where the phrase is never legitimate because the index carries no ruling of its own, and paired it with a positive assertion that "the page that covers it" is present. Verified both directions myself: restoring round 1's index.rst fails exactly that one test; on the fix, 40 OK / 1 skipped, and tests/project 204 OK / 1 skipped.

It also flagged something against its own interest, which is worth recording: I asked for the paragraph to get no longer, and it came out five words longer (175 vs 170). It said so plainly rather than claiming compliance, having traded economy against unavoidable new content. Accepted.

I rebased both this and #943 onto 2dd988862. That is not a maintainer push — it is github-actions[bot], "Bumped build to 1", touching only conda/build and conda/requirements.txt, and the ruleset's strict_required_status_checks_policy means any push to main puts every open PR out of date. Both rebases are content-preserving, checked file-by-file by md5 against the heads I had verified.

One note on my own process: the first --force-with-lease on #943 was rejected, because my local refs/pull/943/head was stale from before an earlier rebase and the lease compared against the wrong sha. That is the lease doing its job; I re-fetched and redid it. Worth saying out loud because an unfetched lease is exactly how a force-push silently discards someone else's work.

Unpublished and yours to merge, once CI reports on the rebased head.