Skip to content

docs: the API docs build prints Sphinx warnings for ambiguous cross-references, an unresolved forward reference and an orphan footnote #2743

Closed

Description

@JarryShaw

Describe the bug
The HTML docs build of main (ab7be2fb0) succeeds but prints six Sphinx warnings. They appear the same with sphinx-autodoc-typehints 3.17.2 and 3.17.4, so they come from our sources, not from the #2742 bump.

Reproduction
Build docs/ in a clean venv from docs/requirements.txt, using the sphinx-build -b html command that make -C docs html runs. The warnings are:

  • IGMP._dispatch: the forward reference Raw in its annotations cannot be resolved (sphinx_autodoc_typehints.forward_reference).
  • docs/source/pcapkit/protocols/link/netlink.rst: footnote [*] is never referenced.
  • DTLS class docstring: Protocol resolves to both pcapkit.protocols.protocol.Protocol and pcapkit.protocols.data.protocol.Protocol.
  • TransType, location <unknown>: resolves to both the const and the vendor class.
  • HandshakeType, location <unknown>: resolves to the SSLv2 and TLS classes under both const and vendor.
  • Query.checksum in pcapkit.protocols.schema.internet.igmpv3: Checksum resolves to both const.tcp and vendor.tcp.

Expected behavior
A clean build: each cross-reference names its target in full, and nothing is left unresolved or orphaned. #709 fixed this same kind of ambiguity before.

System information
Linux, CPython 3.15.2, Sphinx 9.2.0, checkout ab7be2fb0.

Activity

  1. added
    bugIssues reporting a defect (set by the bug report template; a default, not an assessment)
    docsPull requests that change documentation only (docs: subject prefix)
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Nov 3, 2026
  2. added this to the PyPCAPKit v1.6 milestone on Nov 3, 2026
  3. JarryShaw commented on Nov 3, 2026

    @JarryShaw
    OwnerAuthor

    A fix is in progress on a branch off ab7be2fb0. It writes each ambiguous reference as its full target, resolves Raw in IGMP._dispatch, and fixes the orphan footnote in netlink.rst. It also checks other docstrings for the same bare names. A before-and-after docs build in a clean venv will prove the result.

  4. JarryShaw commented on Nov 3, 2026

    @JarryShaw
    OwnerAuthor

    The PR is #2744.

  5. removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Nov 3, 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

    bugIssues reporting a defect (set by the bug report template; a default, not an assessment)docsPull requests that change documentation only (docs: subject prefix)

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions