Skip to content

docs: say which distribution a bare pcap module reference means #1948

Closed

Description

@JarryShaw

pcap is written as a bare literal at most of its mentions, mostly in pcapkit/foundation/engines/{pcap_ct,pypcap,_pcap_backend}.py, plus extraction.py, the engines pages, index.rst and ext.rst. Both PyPCAP and pcap-ct install that same top-level pcap module. The docs say so in one place, docs/source/pcapkit/foundation/engines/3rdparty.rst:188, and a reader meeting a bare pcap elsewhere cannot tell which distribution it means.

A literal footnote does not fit: one defined in rst_epilog is appended to every page and warns as unreferenced wherever it goes unused. Two options:

  1. A label and a substitution. Add .. _pcap-module: above the note at 3rdparty.rst:188, and write each mention as |pcap|_ (or :ref:`pcap <pcap-module>`), following docs: link inventory-less packages through rst_epilog substitutions (#1936) #1939's epilog pattern. Every mention then links to the one explanation.
  2. A glossary term. Add a pcap entry to a glossary that names both distributions, and write each mention as :term:`pcap`. Each mention links to the glossary entry, so it reads like option 1 but adds a glossary page.

I'd take option 1: it reuses an existing mechanism and adds no new page. Mentions that name a distribution (pip install pypcap, the PyPCAP/PCAP_CT extras) stay as they are.

Activity

  1. added
    docsPull requests that change documentation only (docs: subject prefix)
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Oct 19, 2026
  2. JarryShaw commented on Oct 19, 2026

    @JarryShaw
    OwnerAuthor

    option 1

  3. JarryShaw commented on Oct 19, 2026

    @JarryShaw
    OwnerAuthor

    but if necessary, we can create some glossary terms for the documentation with other terms and context in the docs.

  4. JarryShaw commented on Oct 19, 2026

    @JarryShaw
    OwnerAuthor

    Going with option 1: a pcap-module label on the existing note and an epilog |pcap|_ link at each bare mention. Most of these files are also edited by #1946, so the work is stacked on that branch and the PR opens once #1946 merges. A wider glossary is left out of this issue; it can get its own once there are terms that need one.

  5. added
    wipWork in flight - a covering PR is open or an agent is actively on it
    and removed
    needs: decisionWaiting on the maintainer to decide — not blocked by other work
    on Oct 19, 2026
  6. removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsPull requests that change documentation only (docs: subject prefix)

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions