Skip to content

docs: link inventory-less packages through rst_epilog substitutions (#1936) - #1939

Merged
JarryShaw merged 1 commit into
mainfrom
docs/1936-epilog-substitutions
Oct 19, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/1936-epilog-substitutions

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

As ruled on #1928, every third-party project substitution and link target is now defined once, in rst_epilog in docs/source/conf.py. The per-page and per-docstring copies are removed. Package mentions of aenum, cryptography, dpkt, emoji, pcapfile and pyshark are now |pkg|_ links.

Engine, adapter and toolkit names, requirement lists and member-level names stay literals. pcap also stays a literal, because both PyPCAP and pcap-ct install it, so no single project page fits. format_class is unchanged: it names classes, and signatures do not expand substitutions.

The new tests/project/test_docs_epilog_links_1936_unit.py pins the epilog, the links and the absence of duplicate definitions. It fails on main. The pinned docs build reports 0 warnings.

Closes #1936

…1936)

- Define every third-party project substitution and target once, in
  rst_epilog in docs/source/conf.py, and drop the per-page and per-docstring
  copies, which duplicated each other on assembled pages.
- Write the aenum, cryptography, dpkt, emoji, pcapfile and pyshark package
  literals as |pkg|_ links in pages, docstrings and doc comments; engine,
  adapter, toolkit and requirement names, and names below a package, stay
  literals.
- Keep pcap a literal: PyPCAP and pcap-ct both install it, so no one project
  page is its target.
- Leave format_class as is: it names classes, which stay literals, and
  signatures do not expand substitutions.
- Add a test pinning the epilog, the links and the absence of duplicates, and
  point the #1919 test's message at the |pkg|_ form.

Closes #1936
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: running A cross-review is in flight against the current head - no verdict yet labels Oct 19, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

GOOD TO GO at 1ca8b55c9. A Sonnet cross-review rescanned all of pcapkit/ and docs/source/ with its own script. Every |x|_ in use has exactly one definition, in rst_epilog, and every removed per-file URL matches its epilog replacement except for pcap-ct's trailing slash. Its own pinned build of 198 pages has 0 warnings and no duplicate-target messages, and no raw |x|_ appears outside _modules/. The links render on the index, internet, 3rdparty and enum pages. All changed .py files are AST-identical, the new test fails on main, and merge-tree with #1927 is clean. A few package names stay literals inside engine names or requirement phrases (pycrate, requests), which matches the stated rule.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: running A cross-review is in flight against the current head - no verdict yet labels Oct 19, 2026
@JarryShaw JarryShaw moved this to In review in PyPCAPKit Oct 19, 2026
@JarryShaw
JarryShaw merged commit 12b72da into main Oct 19, 2026
53 checks passed
@JarryShaw
JarryShaw deleted the docs/1936-epilog-substitutions branch October 19, 2026 17:06
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Oct 19, 2026
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 19, 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: link inventory-less package references through |name|_ substitutions

1 participant