Skip to content

docs(docs): sweep the Sphinx pages for stale claims, toctree order and markup (#1103) - #1766

Merged
JarryShaw merged 1 commit into
mainfrom
docs/1103-docs
Oct 15, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/1103-docs

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

Please follow the guide below

What is the purpose of your pull request?

Tick the commit type your subject line carries.

  • fix — corrects a defect
  • feat — adds a feature
  • perf — changes performance, not behaviour
  • refactor — changes neither behaviour nor performance
  • test — tests only
  • docs — documentation only
  • ci — workflows or build tooling
  • release — bumps the version or rolls up a distribution
  • chore — anything else

Description

Part of #1103, the whole-repository prose sweep, for the docs slice. It follows the #719 rules: prose only, accuracy first, no churn and no timed context.

  • Directives: versionchanged 1.5.0 on the install section for the narrowed
    all extra and the new dev extra (design: write down what belongs in the all extra, and why #910).
  • Toctrees: Utilities fourth in pcapkit/index.rst; OSPF under Application and
    Miscellaneous last in const and vendor; MH inside the IPv6 extension-header
    block. Conventions, foundation, corekit, misc and utilities preambles follow
    their toctree order.
  • ext.rst: from_data raises UnsupportedCall for caller keywords and warns only
    for keys from _make_data.
  • pep.rst, testing.rst, test-coverage.rst: NULL/LOOP/RAW link types are bound,
    EXPECTED_FAILURES is empty, SKIP holds three, CI runs the fixture tier, the
    dumper round trip is asserted, test: round-trip coverage for every protocol code, dumper and lossless path #1202 is closed.
  • protocol-layer-placement, process, registry-protocol and conf.py: figures
    re-measured against the tree.
  • Markup: nine bold spans that nested an inline literal split, three headings
    in Title Case, bare issue citations linked, timed wording removed.

tests/project: 930 passed, 1 skipped.

Checks:

  • An AST guard holds on every changed .py file.
  • tests/project gives 930 passed and 1 skipped, and every test that reads the edited paths passes.
  • A merged Sphinx build of all nine slices adds no new warnings.
  • A Sonnet cross-review sent this back once. After the fix round, a re-check returned GOOD TO GO.

Not covered here; a round-2 PR follows: the CI-timing and GraalPy figures in workflows.rst, which were not re-derived, and the html-theme block of conf.py.

Refs #1103

…d markup (#1103)

- Directives: versionchanged 1.5.0 on the install section for the narrowed
  all extra and the new dev extra (#910).
- Toctrees: Utilities fourth in pcapkit/index.rst; OSPF under Application and
  Miscellaneous last in const and vendor; MH inside the IPv6 extension-header
  block. Conventions, foundation, corekit, misc and utilities preambles follow
  their toctree order.
- ext.rst: from_data raises UnsupportedCall for caller keywords and warns only
  for keys from _make_data.
- pep.rst, testing.rst, test-coverage.rst: NULL/LOOP/RAW link types are bound,
  EXPECTED_FAILURES is empty, SKIP holds three, CI runs the fixture tier, the
  dumper round trip is asserted, #1202 is closed.
- protocol-layer-placement, process, registry-protocol and conf.py: figures
  re-measured against the tree.
- Markup: nine bold spans that nested an inline literal split, three headings
  in Title Case, bare issue citations linked, timed wording removed.

tests/project: 930 passed, 1 skipped.

Refs #1103
@JarryShaw JarryShaw added the docs Pull requests that change documentation only (docs: subject prefix) label Oct 15, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

Verdict: GOOD TO GO at c4846b423. A Sonnet cross-review checked it (author: Opus), after one fix round.

  • First review, one blocking finding: the name count in protocol-layer-placement.rst was off.
  • Re-check: re-measured from vars(). Link has 10 names including _shipped_proto, Application has 9, they share 6, and Link overrides 4 that Application does not.
  • Toctree reorders: applied as the inventory found, re-verified against main.
  • conf.py: the AST is identical; only comments changed.
  • Tests: tests/project gives 930 passed.
  • Non-blocking: tests/protocols/application/test_layer_placement_unit.py:200 still says seven names; round 2 fixes it.

@JarryShaw JarryShaw added the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 15, 2026
@JarryShaw JarryShaw moved this to In review in PyPCAPKit Oct 15, 2026
@JarryShaw
JarryShaw merged commit 851e82e into main Oct 15, 2026
36 checks passed
@JarryShaw
JarryShaw deleted the docs/1103-docs branch October 15, 2026 17:18
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Oct 15, 2026
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant