Repository navigation
docs: keep the colon off the first line of an attribute's documentation (#2745) - #2746
Merged
Merged
Conversation
JarryShaw
added
docs
Owner
Author
|
GOOD TO GO at
Merge with #2736: the |
JarryShaw
added
review: good-to-go
Contributor
|
Coverage: 94.45% (unit tier, Python 3.15,
Per-file detail: the |
…on (#2745) Napoleon reads the first line of a #: doc comment, or of a property's docstring, as Google's inline "type: description" form wherever a colon outside a role or a literal has text after it. The text before the colon rendered as a Type field and dropped out of the prose -- "Group address", "Protocol Type", "What __proto__ is keyed by", "IGMP version this class reads" -- and the build warned only where that text matched several classes. Two lines split a role across lines, so the colon of :meth: itself was taken and the rendered page carried a second Type, "meth". Each misread line keeps its colon off the first line: " -- ", ". ", or a comma, as each IGMP version property's alias docstring already reads, and the two split roles start on the second line. The IGMPv3 Query.checksum and DTLS reassembler __protocol_type__ lines are byte-identical to #2744's fix of the same two. Comments napoleon would misread that the docs do not render yet are reworded too; inline types written on purpose ("int: Frame counter.") and enum members, which conf.py's restore_enum_member_docstring already restores, are left alone. tests/project/test_doc_comment_first_line_2745_unit.py runs napoleon's own autodoc-process-docstring handler, under conf.py's napoleon settings, over every attribute comment Sphinx's ModuleAnalyzer finds and every property docstring under pcapkit/, and fails on a type that is prose rather than a type expression. Build: 105 rendered Type fields before, 59 after, all real types; warnings 6 before, 4 after, the 4 that #2744 clears (sphinx-autodoc-typehints 3.17.2).
JarryShaw
force-pushed
the
fix/2745-doc-comment-first-line-colon
branch
from
November 3, 2026 16:33
013f22b to
53804e5
Compare
Owner
Author
|
Rebased onto main
GOOD TO GO carries over; apart from these two comment lines the diff is identical. |
JarryShaw
removed
the
review: good-to-go
JarryShaw
added a commit
that referenced
this pull request
Nov 3, 2026
- Breaking: a short CALIPSO, SMF_DPD or MPL Opt Data Len raises ProtocolError, where 1.5.x raised FieldValueError, and a cut after the type octet reads short (#2737), a new entry; AppType.__registries__ is an Info, into the #2734 entry (#2735). - Changed: const packages import their enumerations lazily through pcapkit.utilities.lazy.lazy_exports (#2735); the docs extra pins sphinx-autodoc-typehints 3.17.4 (#2742), as 1.5.0 recorded its pin. - Fixed: the dumps keep a field renamed for clashing with an Info builtin name (#2736). - Folded: the GraalPy leg's timeout and shards into the CI-legs entry (#2741); the #2735 and #2737 rulings into the conventions entry. - No entry for the docs-only #2744 and #2746. - 1.6.0's :func:`bytes` role is :class:`bytes`, so the changelog pages build with no nitpicky warning. Old values measured against v1.5.1. - CHANGELOG.md regenerated; util/changelog_md.py --check passes.
1 of 5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
make pylint,make mypy,make isort)make testpasses, and a test case covers the changeWhat is the purpose of your pull request?
docs— documentation onlyDescription of your pull request and other information
Napoleon reads a colon on the first line of a
#:comment, or of a property docstring, as "type: description". The words before the colon render as a Type field and drop out of the prose, usually with no warning. Built atab7be2fb0, the docs show 105 Type fields. With this change they show 59, all of them real types.:meth:roles that were split across lines now start on the second line.#: int: ...) and enum members (already restored byconf.py) are unchanged.tests/project/test_doc_comment_first_line_2745_unit.pyruns Napoleon's own handler withconf.py's settings over every attribute comment and property docstring. It fails on a type that is really prose.Merge note: there is a one-line textual conflict with #2736 in the
_OrderedMultiDict.__excluded__comment. Whichever PR lands second rebases.Closes #2745