You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: a doc comment whose first line has a colon renders its prose as a Type field #2745
Describe the bug
When an attribute doc comment (#:) has a colon on its first line, Napoleon parses that line as "type: description". The text before the colon goes into a Type field and drops out of the prose. Usually there is no warning, so nothing catches it. #2744 fixed the two cases that did warn: IGMPv3 Query.checksum and the DTLS reassembler's __protocol_type__.
Reproduction
Build docs/ at ab7be2fb0 in a clean venv. In the generated page for pcapkit.protocols.data.internet.igmp, the group attribute shows Type: Group address and its description starts after the colon. Other first lines with the same shape, found by the #2744 review (some may be false positives):
Group address: in protocols/data/internet/igmp.py and igmpv3.py.
Extension data: in protocols/data/application/tls.py.
Unified-header first octet: in protocols/schema/application/dtls.py.
First length octet: in protocols/schema/internet/mh.py.
Protocol Type: in the GRE schema and data modules.
Similar comments in hopopt, ipv6_opts, ipv4, tcp, raw, dccp and radiotap, in the traceflow and reassembly data modules, and in corekit/checksum/internet.py.
The "What __proto__ is keyed by" comments on the Frame, Link, Internet, PCAPNG and pcap Frame classes.
Also, in #2744 the netlink footnote marker leaks framing* into that page's og:description and meta description.
Expected behavior
Every #: comment renders as prose with no stray Type field, and a project test fails on any new first-line colon that Napoleon would misread.
System information
Linux, CPython 3.15.2, Sphinx 9.2.0, sphinx-autodoc-typehints 3.17.2/3.17.4, checkout ab7be2fb0.
A fix is in progress on a branch off ab7be2fb0. It finds the affected comments from the built docs, separates out false positives, rewords the real cases the way #2744 did, and adds a guard test under tests/project/. The netlink meta-description item is being folded into #2744 instead.
Activity
JarryShaw commentedon Nov 3, 2026
A fix is in progress on a branch off
ab7be2fb0. It finds the affected comments from the built docs, separates out false positives, rewords the real cases the way #2744 did, and adds a guard test undertests/project/. The netlink meta-description item is being folded into #2744 instead.JarryShaw commentedon Nov 3, 2026
The PR is #2746.
docs: keep the colon off the first line of an attribute's documentati…
docs: keep the colon off the first line of an attribute's documentati…