Sweep the Sphinx docs for autoclass / autodata / automethod / autoattribute directives naming private _xxx members that nothing public cross-references, and remove them.
The convention, in the owner's words
we'd normally not include _xxx private members in the doc by default unless it carries something that's cross referenced in the public member's docstring/docs, e.g., TypeVar, attributes, etc.
So a private name earns a directive only when something public points at it — a TypeVar, an attribute, a :class:/:data:/:meth: role in a public docstring. A name merely appearing as a signature default is not a cross-reference. pop(key, default=_missing) does not earn _missing a doc entry.
Why it matters
A directive for a private name nothing public references produces a page unreachable from the API anyone actually uses, and it invites the reverse error — a reader treating the name as supported because it is documented.
Scope
docs/source/ currently carries roughly 1,395 autoclass, 163 autoattribute, 155 autofunction and 27 autodata directives, so this is a filter-and-review pass rather than a blanket deletion. For each directive naming a _-prefixed target:
- Grep the public docstrings and the rest of
docs/source/ for a cross-reference to that name.
- No reference → remove the directive (and consider whether the docstring it rendered should go too).
- Reference present → keep, and note what references it.
Known instances worth checking explicitly, since they surfaced while establishing the convention: docs/source/pcapkit/protocols/transport/sctp.rst:111 (_read_cause_missing_param) and :126 (_make_cause_missing_param), and docs/source/pcapkit/protocols/index.rst:230 (__missing__). Dunders may warrant a different rule from single-underscore names — decide that as part of the sweep and write it down.
Deliberately deferred
Do this after the current PR board clears. It touches a large number of .rst files and would conflict with several in-flight PRs that adjust their own doc pages. The owner's framing: "worth sweep the docs after the board to do a cleanup."
Related
The convention was established while closing #667, whose cross-review had required adding an Auxiliaries section documenting pcapkit.corekit.multidict._Missing and ._missing — nothing public referenced either, so that requirement was itself against convention. #661 closed on the adjacent rule that verbatim upstream ports stay verbatim.
Sweep the Sphinx docs for
autoclass/autodata/automethod/autoattributedirectives naming private_xxxmembers that nothing public cross-references, and remove them.The convention, in the owner's words
So a private name earns a directive only when something public points at it — a
TypeVar, an attribute, a:class:/:data:/:meth:role in a public docstring. A name merely appearing as a signature default is not a cross-reference.pop(key, default=_missing)does not earn_missinga doc entry.Why it matters
A directive for a private name nothing public references produces a page unreachable from the API anyone actually uses, and it invites the reverse error — a reader treating the name as supported because it is documented.
Scope
docs/source/currently carries roughly 1,395autoclass, 163autoattribute, 155autofunctionand 27autodatadirectives, so this is a filter-and-review pass rather than a blanket deletion. For each directive naming a_-prefixed target:docs/source/for a cross-reference to that name.Known instances worth checking explicitly, since they surfaced while establishing the convention:
docs/source/pcapkit/protocols/transport/sctp.rst:111(_read_cause_missing_param) and:126(_make_cause_missing_param), anddocs/source/pcapkit/protocols/index.rst:230(__missing__). Dunders may warrant a different rule from single-underscore names — decide that as part of the sweep and write it down.Deliberately deferred
Do this after the current PR board clears. It touches a large number of
.rstfiles and would conflict with several in-flight PRs that adjust their own doc pages. The owner's framing: "worth sweep the docs after the board to do a cleanup."Related
The convention was established while closing #667, whose cross-review had required adding an
Auxiliariessection documentingpcapkit.corekit.multidict._Missingand._missing— nothing public referenced either, so that requirement was itself against convention. #661 closed on the adjacent rule that verbatim upstream ports stay verbatim.