Skip to content

docs: link inventory-less package references through |name|_ substitutions #1936

Closed

Description

@JarryShaw

The owner asked on #1928 for references to packages with no usable inventory (aenum, pcap, pcapfile, pyshark, and the dpkt/scapy/cryptography modules those inventories lack) to link to the project instead of rendering as plain literals. The suggested form is |name|_, with .. |name| replace:: ``name``` and .. name: . pcapkit/protocols/internet/esp.py:158anddocs/source/pcapkit/protocols/internet/esp.rst:166already use this form for|cryptography|`.

Plan:

  • Define each substitution and target once, in rst_epilog in docs/source/conf.py.
  • Use |pkg|_ for package- and module-level names.
  • Keep member-level names as literals, since every one of them would link to the same homepage.
  • Check whether docs(conf): resolve decorated overload aliases and qualify colliding third-party classes (#1917, #1918, #1920) #1929's format_class can emit the same substitutions in type hints.
  • The pinned docs build must stay at 0 warnings. Watch for duplicate-target clashes with section titles such as "PyShark".
  • Extend tests/project/test_docs_unresolvable_roles_1919_unit.py so that the inventory-less names link.

Blocked until #1928 and #1929 merge, because both rewrite the lines involved and #1929 owns conf.py.

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. JarryShaw commented on Oct 19, 2026

    @JarryShaw
    OwnerAuthor

    Scope widened per the owner on #1928: also move the repo's other existing per-file substitution and target pairs into rst_epilog, such as |cryptography| in esp.py/esp.rst. Do this after a repo-wide grep for .. | definitions. #1929 has merged, so this issue now waits only on #1928.

  3. moved this to Blocked in PyPCAPKiton Oct 19, 2026
  4. 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
  5. moved this from Blocked to WIP in PyPCAPKiton 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