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

[JarryShaw]

Describe the bug

Two documentation gaps, both from the maintainer on #719, verbatim:

we did not have a pcapkit.__version__ doc entry and those :file:xxx references need to double check if using the right paths and making sure the rendered links are clickable.

1. No pcapkit.__version__ API entry. Verified: every occurrence of __version__ in the docs is prose, not an API entry —

docs/source/pep.rst:890         "``pcapkit.__version__`` directly, derives ``PCAPKIT_PRERELEASE`` from"
docs/source/releasing.rst:14    "``pcapkit.__version__``. Everything else -- the ``v*`` tag, the GitHub"
docs/source/releasing.rst:22    "Bumping ``pcapkit.__version__`` is done by :file:`util/bump_version.py`"
docs/source/releasing.rst:28    "rewrites the ``__version__`` assignment in ``pcapkit/__init__.py``"
docs/source/releasing.rst:44    "Editing ``__version__`` by hand instead, without also moving"

pcapkit.__version__ is public API and is the single value the release pipeline reads, so it warrants a documented entry rather than only incidental mentions.

2. :file: references need auditing for correctness and clickability. Sweep every :file: role in docs/source/: does the path it names actually exist, is it correct relative to the repository root, and does it render as something a reader can click? The :file: role is semantic markup, not a link — so if the intent is a clickable reference to a file in the repository, :file: may be the wrong role entirely. Establish what the project wants and apply it consistently.

Expected behavior

A documented pcapkit.__version__ entry, and every :file: reference naming a real path with the intended rendering.

System information

Documentation only; no library version involved.

Additional context

Split out of #719, which is the prose sweep; these are structural. Related: #900 moves several of these pages into a subdirectory, which will change what a relative path in them resolves to — so if #900 lands first, re-run the :file: audit afterwards rather than before.

The Sphinx build currently emits 42 warnings, all pre-existing, so measure any delta rather than the total.

[JarryShaw]

Checkable blocker, recorded so this label is not taken on trust: #901.

#901 moves several of these pages into a subdirectory, which changes what a relative path inside them resolves to. Running the :file: audit before that move means auditing paths that are about to change, then auditing them again.

gh issue view 901 -R JarryShaw/PyPCAPKit --json state -q .state

Unblocks when #901 merges. The pcapkit.__version__ entry half does not depend on #901 and could be split out if the move drags — the missing entry is confirmed independent of page location (every __version__ occurrence in the docs is prose: pep.rst:890, releasing.rst:14,22,28,44).

[JarryShaw]

Adding one concrete instance to this issue's scope, found while building #906.

pcapkit.corekit.enum has no documentation page at all. docs/source/pcapkit/corekit/index.rst's toctree omits it — verified, grep -n enum on that file returns nothing. So neither EnumRegistry nor the new EnumLookup is autodoc'd, and consequently every :class:~pcapkit.corekit.enum.*`` reference in docs/source/conventions.rst is unresolved.

That matters here because conventions.rst is the page recording the registry design rulings and it leans on those cross-references throughout — the "Where the registry protocol lives" section names EnumRegistry.get, get_all, register and register_alias as roles, and none of them link anywhere.

Pre-existing rather than introduced, and harmless in the sense that the build does not fail: docs/source/conf.py sets no nitpicky and the build uses no -W, so unresolved cross-references pass silently. That is precisely why it has survived — it is the same class of problem as this issue's :file: audit, where a reference can look right in source and render as nothing.

So the audit should cover both shapes: a role that names a real path but renders unclickable, and a cross-reference whose target was never added to a toctree. The second is only findable by checking what the toctrees actually include against what the prose references.

Note the sequencing already recorded here still applies — #901 moves several pages, which changes what a relative path resolves to, so run the audit after that lands. This addition does not change that.

[JarryShaw]

Unblocked — the sequencing recorded here is discharged. This issue's own last comment said:

#901 moves several pages, which changes what a relative path resolves to, so run the audit after that lands.

#901 is closed and its PR #912 merged as 9806f16aa, moving conventions.rst, releasing.rst, testing.rst, workflows.rst and pep.rst into docs/source/contributing/. Checkable:

$ gh issue view 901 -R JarryShaw/PyPCAPKit --json state -q .state
CLOSED

Removing blocked, marking wip, worker dispatched on both halves of the scope recorded above — the :file: reference audit and the missing pcapkit.__version__ entry — plus the addition made while building #906: pcapkit.corekit.enum has no documentation page at all, so neither EnumRegistry nor EnumLookup is autodoc'd and every :class:~pcapkit.corekit.enum.*`` reference in the convention docs resolves to nothing.

One caveat carried forward, because it is why this class of defect survives: docs/source/conf.py sets no nitpicky and the build uses no -W, so an unresolved cross-reference renders as plain text and CI stays green. The audit has to look at rendered output or at toctree membership, not at the warning count.