Skip to content

Commit abb6682

Browse files
committed
docs(CHANGES) Class-level name rendering
why: The branch changes what a reference page shows for every field, key, enum member, and class variable, against behavior users of the published release already have. what: - Record the withheld undescribed class variable as a breaking change, with the description styles and config value that restore it - Describe inherited descriptions, module constant values, and the machinery-member filter - Limit Fixes to the three regressions a published release exhibited, leaving out repairs to behavior this branch itself introduced - Note the how-to and the packages whose reference fields gained descriptions
1 parent 850c02a commit abb6682

1 file changed

Lines changed: 71 additions & 0 deletions

File tree

‎CHANGES‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,77 @@ $ uv add gp-sphinx --prerelease allow
1818

1919
<!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
2020

21+
### Breaking changes
22+
23+
#### An undescribed class variable is withheld from the reference
24+
25+
A `ClassVar` nobody describes no longer renders. Class variables are
26+
often internal — a registry, a cached sentinel, a counter — and a page
27+
listing them bare says less than one that omits them. The cost is that a
28+
class variable you meant to publish goes missing rather than looking
29+
empty.
30+
31+
Describe it — in an `Attributes` entry, a docstring under the
32+
assignment, or a `#:` comment — and it returns. To render them all
33+
regardless, set `gp_typehints_show_undocumented_class_vars = True`. See
34+
{ref}`class-level-names`. (#72)
35+
36+
### What's new
37+
38+
#### A description written on the base reaches every subclass
39+
40+
A dataclass field or typed-dictionary key described where it is declared
41+
now carries that description to every subclass inheriting it. A base
42+
documenting a wide option set no longer obliges each subclass to restate
43+
it. (#72)
44+
45+
#### Module constants render their value
46+
47+
A constant described in its module docstring's `Attributes` section now
48+
renders the value the live module holds, and registers in the Python
49+
domain as data, so a cross-reference to it resolves. (#72)
50+
51+
#### Machinery members stay off the page
52+
53+
`private-members` is on by default, so the private attributes Python's
54+
own machinery writes into a class — an abstract base's registry cache, a
55+
named tuple's field list — reached the page as names no docstring could
56+
describe. They are filtered out. A project wanting one back answers from
57+
its own `autodoc-skip-member` handler, which is asked first. (#72)
58+
59+
### Fixes
60+
61+
#### A described member keeps its description
62+
63+
An `Attributes` entry naming a class variable, an init-only field, a
64+
property, a method, or a nested class lost its description once autodoc
65+
rendered that member, leaving the entry empty. Each now carries the
66+
prose its author wrote. (#72)
67+
68+
#### A described member keeps its signature
69+
70+
Describing a member cost the reader the annotation and value autodoc
71+
computes from the live class — an enum member rendered without its
72+
value, a constant without any. Both are restored. (#72)
73+
74+
#### Documenting a typed dictionary keeps its subclasses' keys
75+
76+
Documenting a typed dictionary alongside its subclasses made every key
77+
the subclasses inherit disappear from their own pages. (#72)
78+
79+
### Documentation
80+
81+
#### Class-level names have a how-to
82+
83+
The rules every class-level name follows — the three places a
84+
description can live, what each shape renders, and which names are
85+
withheld — are written down. See {ref}`class-level-names`. (#72)
86+
87+
#### More fields describe themselves in the API reference
88+
89+
The layout, badges, and Vite-builder packages now say what each field
90+
holds rather than rendering a bare name and its type. (#72)
91+
2192
### Development
2293

2394
#### Lint toolchain: ruff 0.16

0 commit comments

Comments
 (0)