docs: Document Attributes for NamedTuple and dataclass fields#548
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #548 +/- ##
==========================================
- Coverage 61.34% 61.31% -0.03%
==========================================
Files 40 40
Lines 6571 6566 -5
Branches 1104 1104
==========================================
- Hits 4031 4026 -5
Misses 1946 1946
Partials 594 594 ☔ 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
3bb4cfb to
ceb8bb1
Compare
why: Autodoc renders every dataclass field, so the undocumented Popen mirror fields shipped bare in the API reference with no hint of their accepted values, platform scope, or what each default means. what: - Document every SubprocessCommand field in an Attributes section - Note which fields are POSIX-only or Windows-only - Spell out the sentinel defaults (-1, (), None) and the text-mode interaction between text, universal_newlines, encoding, errors
why: Autodoc renders every field whether or not it is described, so these shipped to the API reference bare, and the NamedTuple fields shipped as "Alias for field number 0". what: - Document SyncError, SyncResult, and VCSLocation fields - Document GitRemote fetch/push URL fields - Describe GitStatus fields as the "git status --porcelain=2" branch headers they hold, including when each is None
why: Autodoc renders every dataclass field, so the parsed URL fields shipped bare in the API reference. Rule's per-field docstrings also sat one field below what they described, so readers matched "Weight: Higher is more likely to win" to is_explicit. what: - Move Rule's field docstrings into an Attributes section, paired with the field each describes, and cover defaults and weight - Document the parsed fields of GitBaseURL, HgBaseURL, SvnBaseURL, including which sentinel each carries when a rule captures nothing - Document region and rev on GitAWSCodeCommitURL, and rev on the pip URL parsers
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
bc12f17 to
bcccf11
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 the docstring describes it, so fields that predate theAttributesrule reached the API reference as stubs —NamedTuplefields as "Alias for field number 0", dataclass fields bare. This adds a NumPy-styleAttributessection to the classes that were missing one, covering the subprocess command mirror, the sync result types and git status/remote records, and the URL rule and parser fields.Rule's existing per-field docstrings also sat one field below what they described, pairing "Weight: Higher is more likely to win" withis_explicit; those move into theAttributessection beside the field each belongs to. 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 for every newly documented field (
duplicate object description of ..., other instance in ...), in_internal/subprocess.py,sync/base.py,sync/git.py,url/base.py,url/git.py,url/hg.py, andurl/svn.py. The NumPy preprocessor emits an.. attribute::for each entry while autodoc separately renders the same field, so both register the object. Trunk builds warning-free. Left unsuppressed here — the fix belongs in gp-sphinx and is landing there separately.Closes #547