Skip to content

docs: roles naming aenum, pcapfile, pyshark and pcap still render as unresolved chips outside conventions.rst #1920

Closed

Description

@JarryShaw

#934 part C settled this: a package whose objects.inv holds no py: objects cannot be cross-referenced, and its roles become literals. The owner agreed those packages cannot be cross-referenced. docs/source/conf.py:169-180 states the same policy. AenumRoleExclusionTests (tests/project/test_conventions_doc_claims.py:696) enforces it for conventions.rst only.

On 95caa8b36, roles naming those packages remain elsewhere:

  • format_aenum_class (conf.py:589-622), added for docs: aenum and stdlib enum unions render as IntEnum | IntEnum and Enum | Enum #1858, emits a :py:class: role for every aenum class. That fills the const, corekit and protocol pages with unresolved aenum.IntEnum, aenum.StrEnum and aenum.IntFlag chips.
  • engines/3rdparty.rst and toolkit/3rdparty.rst use :mod:pcap``, pcapfile.* and `pyshark.*` roles.
  • corekit/fields/numbers.py uses aenum.extend_enum.

Fix: have the formatter return a qualified literal, which keeps #1858's disambiguation; demote the hand-written roles; and widen the guard test to docs/ and pcapkit/. If the formatter's role was a deliberate exception, the scope narrows to the hand-written roles.

Found in the #1103 round-4 sweep.

Activity

  1. added
    docsPull requests that change documentation only (docs: subject prefix)
    pendingAccepted and unstarted - nobody is on it and nothing blocks it
    wipWork in flight - a covering PR is open or an agent is actively on it
    and removed
    pendingAccepted and unstarted - nobody is on it and nothing blocks it
    on Oct 19, 2026
  2. added a commit that references this issue on Oct 19, 2026
  3. JarryShaw commented on Oct 19, 2026

    @JarryShaw
    OwnerAuthor

    The remaining scope (the aenum roles in the apptype and option_type vendor templates and their const modules) is unblocked now that #1927 has merged. A worker is converting those to |aenum|_ and literals, following #1939's rst_epilog, and lifting the exclusions in the #1919 and #1936 guards.

  4. 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