Skip to content

docs: add pcapkit.__version__ entry and the missing corekit.enum page - #919

Merged
JarryShaw merged 1 commit into
mainfrom
fix/902-version-entry-file-audit-enum-docs
Sep 29, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
fix/902-version-entry-file-audit-enum-docs

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

Please follow the guide below

What is the purpose of your pull request?

  • docs — documentation only

Description of your pull request and other information

Closes #902.

  • pcapkit.__version__: added under a new "Package Metadata" section on
    docs/source/pcapkit/index.rst, matching where other top-level pcapkit
    data lives -- it had no API entry, only prose mentions.
  • pcapkit.corekit.enum had no doc page at all: added
    docs/source/pcapkit/corekit/enum.rst (shape matches module.rst/field.rst)
    and wired it into corekit/index.rst's toctree. EnumLookup/EnumRegistry
    now get real id anchors, and every :class:~pcapkit.corekit.enum.*``
    reference in contributing/conventions.rst resolves to a real `href` --
    verified against a built HTML tree, not a warning count, since `conf.py`
    sets no `nitpicky` and the build uses no `-W`.
  • :file: audit: swept 498 occurrences (210 unique targets) across
    docs/source/, pcapkit/ and tests/. Fixed 7 wrong ones: two abbreviated
    pcapkit/protocols/{internet/hip,transport/tcp}.py citations missing their
    directory prefix in tests/protocols/test_option_roundtrip_unit.py, and
    five references in tests/corekit/test_sentinel_exports_unit.py still
    pointing at docs/source/conventions.rst's pre-refactor(docs): move the process pages out of the docs top level #901-move location. The rest
    are either external files, gitignored generated fixtures, deliberate
    historical references, or abbreviated mentions with directory context
    already established in the same file -- not defects.

Sphinx warnings: 58 on origin/main, 61 here (+3), all
duplicate object description for the three private methods explicitly
re-automethod'd in enum.rst -- the same pattern infoclass.rst already
uses for Info.__init_subclass__/__post_init__.

Docs-only change (plus two comment-only :file: fixes in existing tests, no
behaviour touched), so there is no coverage delta to claim.

- Documented pcapkit.__version__ under a new "Package Metadata" section
  on the pcapkit module page, next to how other top-level pcapkit
  attributes are documented; it had no API entry, only prose mentions.
- Added docs/source/pcapkit/corekit/enum.rst for pcapkit.corekit.enum,
  which had no page at all, so EnumLookup/EnumRegistry were undocumented
  and every :class:`~pcapkit.corekit.enum.*` reference in the convention
  docs resolved to nothing. Wired into corekit/index.rst's toctree.
- Audited every :file: role under docs/source, pcapkit/ and tests/ (498
  occurrences, 210 unique targets); fixed the 7 that named a stale or
  wrong path: two abbreviated pcapkit/protocols/*.py citations missing
  their directory prefix, and five references in a just-merged test file
  still pointing at conventions.rst's pre-move location.

Verified against a fresh HTML build: EnumLookup/EnumRegistry get real
id anchors and the conventions.rst cross-references into them now
render as real hrefs. Sphinx warnings: 58 on origin/main, 61 here (+3,
all "duplicate object description" for explicitly-redeclared private
methods, the same pattern already used on Info.__init_subclass__).
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Sep 29, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

GOOD TO GO — cross-review verdict at head 55addee75, produced on Opus (author was Sonnet), briefed to falsify. Nothing load-bearing overturned.

Independently re-derived on the built tree, not from warning counts: the docs build exits 0 on both trees; the warning delta is exactly +3, all duplicate object description for the three explicitly-redeclared private methods; docs/source/pcapkit/corekit/infoclass.rst:11-19 is a real precedent that already contributes 2 identical warnings to the baseline, and its Info.__init_subclass__ renders twice with an id="id0" anchor on unmodified main — so this is pre-existing house behaviour, not something this PR introduces. id="pcapkit.__version__" resolves against pcapkit, not pcapkit.all.

Three corrections to the numbers, none blocking, all measured by me:

  • :file: occurrences are 517, not 498. git grep -o -e ':file:[^]*' -- docs/source pcapkit testson3766c3c: 517 occurrences (413 in tests/, 74 in docs/source/, 30 in pcapkit/`), and 211 unique targets, not 210. Unchanged at 517 on this head, as expected — the fixes rewrite paths, they do not add roles. The classification work is unaffected; 15 of the ~72 non-existent targets were re-sampled and none is a genuine stale path.
  • The five failures are not all one test. On unmodified 3766c3c09: three are subTests of SentinelExportTests.test_star_import_hands_back_the_canonical_object (module= pcapkit.corekit.module, pcapkit.corekit.fields.field, pcapkit.corekit.enum), and two are NoValueIsTheDocumentedFieldDefaultTests.test_an_undefaulted_field_reports_the_sentinel and test_setting_and_deleting_a_default_round_trips_through_the_sentinel. Same root cause, so "pre-existing isolation hazard" stands, but the attribution in the hand-back over-stated it.
  • Relayed unverified: the cross-references into enum.html were counted at 24 hrefs over 9 unique targets against a baseline of 0. I did not rebuild to re-derive that; the direction is what matters and it agrees.

CI at this head: 53 CheckRuns pass, 0 fail, the five Python 3.10–3.14 legs still in progress. Unpublished and unmerged — yours to merge.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Sep 29, 2026
@JarryShaw
JarryShaw merged commit ada85bb into main Sep 29, 2026
63 checks passed
@JarryShaw
JarryShaw deleted the fix/902-version-entry-file-audit-enum-docs branch September 29, 2026 15:18
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Sep 29, 2026
@JarryShaw JarryShaw added this to the 1.5 milestone Oct 6, 2026
@JarryShaw JarryShaw moved this to Done in PyPCAPKit Oct 6, 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.

docs: add a pcapkit.__version__ entry and audit every :file: reference

1 participant