Document dataclass fields that ship as bare autodoc stubs#721
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #721 +/- ##
=======================================
Coverage 52.36% 52.36%
=======================================
Files 26 26
Lines 3726 3726
Branches 747 747
=======================================
Hits 1951 1951
Misses 1471 1471
Partials 304 304 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
tony
force-pushed
the
attributes-backfill
branch
from
July 26, 2026 00:57
0e5bf65 to
c4fa6ca
Compare
why: autodoc renders every dataclass field whether or not it is described, so the hook fields reach the API reference bare with no indication of when tmux fires them. The man-page text already sits beside each field as a source comment, invisible to readers of the published docs. what: - Add an Attributes section to Hooks covering every hook field - Note that an empty SparseArray means tmux reported no commands
why: autodoc renders every dataclass field whether or not it is described, so the server, session, window, and pane option fields reach the API reference bare. Readers cannot tell what a field controls without opening the tmux man page and translating the underscored name back to its hyphenated option. what: - Add Attributes sections to ServerOptions, SessionOptions, WindowOptions, and PaneOptions describing each option field - Note in each summary that a field keeps its default when tmux reports no value for that option
why: autodoc renders every dataclass field whether or not it is described, so Obj's tmux format fields reach the API reference bare, both on Obj and on the Pane, Session, and Window pages that inherit them. A reader cannot tell what a field reports without opening the tmux man page and matching the token by name. what: - Add an Attributes section to Obj covering the server handle and every tmux format token it carries - Describe client_mode_format from tmux's client mode default format, the one token the man page's FORMATS table omits - Note in the summary that tmux reports each token as a string, and that None means the token was out of the listing's scope, absent from the running tmux, or expanded to empty
why: autodoc renders every dataclass field whether or not it is described, so Pane's option scope, hook scope, and server fields reach the API reference bare. A reader cannot tell which tmux flag a scope selects, or what the server handle is used for, without reading OptionsMixin and HooksMixin. what: - Add an Attributes section to Pane covering default_option_scope, default_hook_scope, and server - Name the tmux flag each scope sends, and what an unset scope means for set-option, show-options, set-hook, and show-hooks
why: autodoc renders every dataclass field whether or not it is described, so Window's option scope, hook scope, and server fields reach the API reference bare. A reader cannot tell which tmux flag a scope selects, or what the server handle is used for, without reading OptionsMixin and HooksMixin. what: - Add an Attributes section to Window covering default_option_scope, default_hook_scope, and server - Name the tmux flag each scope sends, and what an unset scope means for set-option, show-options, set-hook, and show-hooks
why: autodoc renders every dataclass field whether or not it is described, so Session's option scope and hook scope fields reach the API reference bare, and the server entry carries a type with no text. Both scopes default to None, which reads as "no scope" rather than the session scope tmux actually applies. what: - Add an Attributes section to Session covering default_option_scope and default_hook_scope - Explain that an unset scope sends no flag, which tmux resolves as session scope, and that OptionScope.Session maps to the same - Describe the server handle on the existing Parameters entry
why: The unreleased entry did not record that class fields now carry descriptions where the API reference renders them. what: - Note the described fields under Documentation
tony
force-pushed
the
attributes-backfill
branch
from
July 26, 2026 01:22
657e859 to
851e95f
Compare
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
1 participant
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.
Autodoc renders every field of a dataclass whether or not the docstring describes it, so a field no
Attributessection names reaches the API reference bare, and aNamedTuplefield reaches it as "Alias for field number 0". This adds NumPyAttributessections to the classes that predate theAGENTS.mdrule requiring one: the option and hook containers inlibtmux._internal.constants,Objinlibtmux.neo, and the scope and server fields onPane,Session, andWindow. Each entry names the field's type, what it holds, which tmux option or format token it maps to, and what its default or empty value means. Docstrings only — no code, signature, or field-order changes.Gates run and passing:
just ruff-format,just ruff,uv run mypy .,just test,just build-docs.The docs build, warning-free on trunk, now reports a duplicate object description for each newly described field (
duplicate object description of ..., use :no-index: for one of them). The NumPy preprocessor emits an.. attribute::for eachAttributesentry while autodoc also renders the field, so both register the same object. The build still succeeds. Left unsuppressed here deliberately: the fix belongs in the preprocessor upstream in gp-sphinx, not in asuppress_warningsentry indocs/conf.py.Closes #720