Skip to content

docs: link bare pcap module mentions to the PyPCAP/pcap-ct note (#1948) - #1952

Merged
JarryShaw merged 3 commits into
mainfrom
docs/1948-pcap-module-link
Oct 19, 2026
Merged

JarryShaw merged 3 commits into
mainfrom
docs/1948-pcap-module-link

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

What is the purpose of your pull request?

  • docs — documentation only

Description of your pull request and other information

Links each rendered bare pcap module mention to the note explaining that PyPCAP and pcap-ct both install that module (#1948, option 1). The note in engines/3rdparty.rst gets a pcap-module label, and |pcap|_ in rst_epilog targets it.

An epilog target cannot reach a label on another page: an indirect target fails off its own page, and :ref: renders plain text rather than a literal. So a doctree-resolved handler in conf.py, link_pcap_module, points the link at the note's page from every other page, and warns if the label is missing.

index.rst's PCAP Wikipedia link becomes anonymous, because target names fold case and its named target clashed with pcap. Code, distribution names, engine names and the file format stay literal.

The hook leaves singlehtml's single-page anchor alone and writes the plain literal where a builder has no page for the note (latex without it). tests/project/test_docs_pcap_module_link_1948_unit.py, including real singlehtml and latex builds, fails without the change. The docs build on the pinned versions has no warnings.

Closes #1948

- Label the note in engines/3rdparty.rst that explains both distributions
  install the same top-level pcap module, as pcap-module.
- Define |pcap|_ in rst_epilog with that label's anchor as its target, and add
  a doctree-resolved hook, link_pcap_module, that points it at the note's page
  from every other page, so it renders as a linked literal like |pkg|_.
- Write the rendered module mentions in docs pages and engine docstrings as
  |pcap|_; keep distribution names, code, engine and adapter names, the file
  format, and the note itself as literals.
- Make index.rst's PCAP file-format link anonymous, since target names fold
  case and its named target clashed with the epilog's pcap target.
- Pin the label, the epilog entry, the hook and the bare-literal scan in
  test_docs_pcap_module_link_1948_unit.py, and let the #1936 guard accept the
  internal target.

Closes #1948
- link_pcap_module leaves the bare anchor alone when the builder's URI for
  the note's page is itself a fragment, as singlehtml's is, instead of
  writing a second '#' into it.
- It replaces each link with its literal when the builder raises NoUri for
  the note's page, as latex does when its document set leaves the note out,
  instead of failing the build.
- Build a scratch project under singlehtml and latex in the #1948 test, so
  the hook is exercised by real builders rather than a mock.

Closes #1948
@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

NEEDS CHANGES at bc9c279d8, one wording nit. A Sonnet delta review checked both builder rules against the Sphinx 9.1 source. Only singlehtml returns a # page URI, so its bare anchor is left alone. latex and texinfo raise NoUri for a page outside the document set, so the link becomes its literal. text and man build with 0 warnings. The new builder tests fail without the fix, and the html build has 0 warnings. The one change, in a follow-up commit: a test docstring says the build "used to die", which is timed wording.

@JarryShaw JarryShaw added review: needs-changes Cross-review at the current head says changes are required; see the verdict comment and removed review: running A cross-review is in flight against the current head - no verdict yet labels Oct 19, 2026
- Restate the latex builder test's docstring as what it pins: latex has no
  URI for a page outside its document set, so each link is written as its
  literal.
- Word the KEPT allowlist comment without "still".

Closes #1948
@JarryShaw JarryShaw added review: running A cross-review is in flight against the current head - no verdict yet and removed review: needs-changes Cross-review at the current head says changes are required; see the verdict comment labels Oct 19, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

GOOD TO GO at 559956780. A Sonnet delta review confirmed the new commit rewords only the latex test's docstring and the KEPT comment, with no assertion changed. The new wording matches what the test asserts, and no history wording is left in the lines the PR adds. The test file passes in both the repo venv and the pinned docs venv (17 passed).

@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 c3ac3d7 into main Oct 19, 2026
8 checks passed
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Oct 19, 2026
@JarryShaw
JarryShaw deleted the docs/1948-pcap-module-link branch October 19, 2026 18:52
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 19, 2026
@JarryShaw JarryShaw added this to the PyPCAPKit v1.5 milestone Oct 26, 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: say which distribution a bare pcap module reference means

1 participant