docs(api): Document NamedTuple, dataclass, and TypedDict fields - #567
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #567 +/- ##
=======================================
Coverage 83.72% 83.72%
=======================================
Files 32 32
Lines 4596 4596
Branches 928 928
=======================================
Hits 3848 3848
Misses 497 497
Partials 251 251 ☔ 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
cb00d4e to
9cd01b9
Compare
why: Autodoc renders the plan dataclasses field by field, so the undocumented ones ship to the API reference bare. what: - Add Attributes sections to PlanEntry, PlanSummary, PlanRenderOptions, and PlanResult - Spell out what None means for the optional status fields and which sync flags drive each render option
why: SearchToken is a NamedTuple, so an undocumented field reaches the API reference as "Alias for field number 0". what: - Add Attributes sections to SearchToken and SearchPattern - Record that fields carries the "field:" prefix scope and that raw holds the pattern before escaping or word-boundary wrapping
why: StatusCheckConfig fields render bare in the API reference, with no hint of which CLI flag sets them or what they cost. what: - Add an Attributes section to StatusCheckConfig - Record that max_concurrent bounds the async semaphore and that detailed adds branch and ahead/behind at the price of extra git invocations per repository
why: SyncPlanConfig fields render bare in the API reference, hiding that offline overrides fetch. what: - Add an Attributes section to SyncPlanConfig - Record that fetch refreshes remote refs before status is read, and that offline suppresses it and plans repos with uncomparable remote state as updates
why: RawConfigDict keys render bare in the API reference, while the sibling entry TypedDicts already describe theirs. what: - Add an Attributes section to RawConfigDict - Contrast it with ConfigDict: paths stay as written and shorthand entries are not yet expanded
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
1cb5e21 to
5f91b2e
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
NamedTuple,dataclass, orTypedDictwhether or not it is described, so the ones we never documented reach the API reference asAlias for field number 0or as a bare name and type. This adds NumPy-styleAttributessections to the plan dataclasses, the search token and pattern, the status and sync plan config objects, andRawConfigDict, so each field carries its meaning: whatNonestands for on the optional status fields, which CLI flag drives which option, and where a value sits relative to its siblings. 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 succeeds but now emits duplicate-object warnings, one per documented field, of the form
duplicate object description of ..., use :no-index: for one of them. They come from the NumPy preprocessor emitting an.. attribute::directive for each entry while autodoc renders the same field. That is a gp-sphinx issue, being fixed upstream, sodocs/conf.pyis untouched here.Closes #566