Repository navigation
docs: clear the API docs build's Sphinx warnings (#2743) - #2744
Merged
Merged
Conversation
JarryShaw
added
docs
Owner
Author
|
GOOD TO GO at
Non-blocking: the netlink footnote marker leaks "framing*" into the page's meta description. Other |
JarryShaw
added
review: good-to-go
The HTML build of main succeeded with warnings, each a link that was wrong
or missing:
- IGMP._dispatch returns Type[Raw], but Raw was imported only inside the
method, so the annotation could not resolve and rendered unlinked. Raw is
imported under TYPE_CHECKING as well; nothing changes at run time.
- Netlink's footnote citing netlink(7) and RFC 3549 had no reference; the
sentence naming Netlink references it, outside the paragraph the meta tags quote.
- Napoleon reads a doc-comment's first-line colon as "type: description".
The IGMPv3 Query.checksum comment ("Checksum: ...") and the DTLS
reassembler's __protocol_type__ comment ("... An extension point: ...")
had their prose taken as the type, which suffix-matched Checksum and
Protocol to several classes and dropped the text from the page. Both keep
the colon off the first line, as the IGMP schema's checksum does.
- sphinx-autodoc-typehints renders a legacy TypeVar's string constraints
verbatim, so Deferred's _KT left TransType and HandshakeType bare, and the
latter linked to the SSLv2 enumeration. The conf.py hook
qualify_type_parameters points a bare name in a type-parameter list at
the pcapkit class its module binds.
Build: 6 warnings before, 0 after (sphinx-autodoc-typehints 3.17.2).
JarryShaw
force-pushed
the
fix/2743-docs-build-warnings
branch
from
November 3, 2026 15:03
4ed21aa to
4cb451b
Compare
Owner
Author
|
GOOD TO GO at The only change since |
5 tasks done
Contributor
|
Coverage: 94.45% (unit tier, Python 3.15,
Per-file detail: the |
JarryShaw
added a commit
that referenced
this pull request
Nov 3, 2026
…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
added a commit
that referenced
this pull request
Nov 3, 2026
…on (#2745) (#2746) 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
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
This clears the Sphinx warnings from the HTML docs build on main. A clean-venv build goes from six warnings to none (sphinx-autodoc-typehints 3.17.2).
IGMP._dispatch: importsRawunderTYPE_CHECKINGas well, so its return type now links. Nothing changes at run time.netlink.rst: the netlink(7) / RFC 3549 footnote is now referenced from thestruct nlmsghdrframing it documents.Query.checksumand the DTLS reassembler's__protocol_type__: Napoleon read the first-line colon in each doc comment as "type: description". That made the prose ambiguous cross-references and dropped it from the page. The colon now stays off the first line.Deferred._KTprints its string constraints bare, soTransTypeandHandshakeTypewere ambiguous, andHandshakeTypelinked to the SSLv2 enum. A newconf.pyhook,qualify_type_parameters, points each bare type-parameter name at the class its module binds. It changes those links and nothing else; the PR also addstests/project/test_docs_type_parameters_2743_unit.py.Closes #2743