Skip to content

docs: add a glossary for terms with several meanings (registry, schema/data model/info, default engine) #1949

Closed

Description

@JarryShaw

A few words in the docs carry several meanings, and no single page tells them apart, so a link to one explanation cannot resolve them:

  • registry: a pcapkit.const enumeration (pcapkit/const/index.rst:14), an upstream IANA registry (index.rst:117), the registration functions (foundation/registry.rst), and EnumMeta.registry (pcapkit/protocols/schema/schema.py:1259). contributing/conventions/test-coverage.rst:11 uses two of these senses close together.
  • schema / data model / info: defined only in the extension guide (ext.rst). Protocol.data is raw bytes, Protocol.info returns a data model but its docstring calls it an "Info dict" (protocol.py:607), and Protocol.schema is "Schema data".
  • default engine: used across the engine and extraction docs, never defined. engines/builtin.rst does not use the word.

Proposal: add docs/source/glossary.rst, a .. glossary:: holding only these terms. Each entry gets one or two sentences saying which sense applies, plus a link to the page that explains it, so it never becomes a second explanation. Put it in the "Guides & Changelog" toctree between demo and changelog. Point the ambiguous mentions at it with :term:, and fix the "Info dict" docstring.

Terms that have one canonical explanation keep linking to it (:ref:/:doc: or an rst_epilog substitution, as in #1948), not to the glossary. A test pins the entries and that every :term: resolves.

Blocked until #1946 and #1948 merge: both edit protocol.py and the engines pages this would touch.

Activity

  1. added
    docsPull requests that change documentation only (docs: subject prefix)
    blockedDeferred pending another issue or decision; see the last comment for what unblocks it
    on Oct 19, 2026
  2. moved this to Blocked in PyPCAPKiton Oct 19, 2026
  3. added
    wipWork in flight - a covering PR is open or an agent is actively on it
    and removed
    blockedDeferred pending another issue or decision; see the last comment for what unblocks it
    on Oct 19, 2026
  4. moved this from Blocked to WIP in PyPCAPKiton Oct 19, 2026
  5. removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Oct 19, 2026
  6. added this to the PyPCAPKit v1.5 milestone on Oct 26, 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

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions