Repository navigation
docs: add a pcapkit.__version__ entry and audit every :file: reference #902
Description
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:xxxreferences 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.
Activity
[-]docs[/-][+]docs: add a pcapkit.__version__ entry and audit every :file: reference[/+]JarryShaw commentedon Sep 29, 2026
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.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 commentedon Sep 29, 2026
Adding one concrete instance to this issue's scope, found while building #906.
pcapkit.corekit.enumhas no documentation page at all.docs/source/pcapkit/corekit/index.rst's toctree omits it — verified,grep -n enumon that file returns nothing. So neitherEnumRegistrynor the newEnumLookupis autodoc'd, and consequently every:class:~pcapkit.corekit.enum.*`` reference indocs/source/conventions.rstis unresolved.That matters here because
conventions.rstis the page recording the registry design rulings and it leans on those cross-references throughout — the "Where the registry protocol lives" section namesEnumRegistry.get,get_all,registerandregister_aliasas 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.pysets nonitpickyand 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 commentedon Sep 29, 2026
Unblocked — the sequencing recorded here is discharged. This issue's own last comment said:
#901 is closed and its PR #912 merged as
9806f16aa, movingconventions.rst,releasing.rst,testing.rst,workflows.rstandpep.rstintodocs/source/contributing/. Checkable:Removing
blocked, markingwip, worker dispatched on both halves of the scope recorded above — the:file:reference audit and the missingpcapkit.__version__entry — plus the addition made while building #906:pcapkit.corekit.enumhas no documentation page at all, so neitherEnumRegistrynorEnumLookupis 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.pysets nonitpickyand 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.