docs: add :no-index: to page-level autoclass directives (PR 2 of 2)#407
Merged
docs: add :no-index: to page-level autoclass directives (PR 2 of 2)#407
Conversation
PR 2 of the 2-PR Sphinx cleanup sequence. Drops `make html` warning count from 2,170 to 635 (71% reduction; 1,535 fewer warnings) by suppressing class-level cross-reference duplicate registrations between page-level RST files and autosummary stubs. Sphinx itself recommends `:no-index:` for the duplicating side per the warning text. Architecture: page-level autoclass directives in `docs/api/*.rst` (78 sites across 23 files) get `:no-index:`; the autosummary stubs in `docs/api/_autosummary/*.rst` remain canonical for cross-references (`:class:\`DiDResults\`` and similar resolve to stub pages). Page-level pages still render member docs inline (no visual change to RST users); only the global cross-reference inventory is affected. Approach validated empirically before the global pass via spike on `bacon.rst` (3 directives): all 19 baseline duplicates citing `api/bacon` cleared (100% drop on the spike's local scope), 0 errors, all rendered HTML members preserved (114 `<dt>` tags, fit/get_params/ set_params methods all visible). Spike pass criteria met; global pass applied via single `sed` invocation per file. Per-file breakdown (78 directives total): - had.rst, staggered.rst: 8 each - honest_did.rst: 6 - power.rst: 5 - results.rst, chaisemartin_dhaultfoeuille.rst, estimators.rst, profile.rst: 4 each - bacon.rst, continuous_did.rst, efficient_did.rst, imputation.rst, local_linear.rst, pretrends.rst, two_stage.rst: 3 each - business_report.rst, diagnostic_report.rst, stacked_did.rst, triple_diff.rst, trop.rst, wooldridge_etwfe.rst: 2 each - diagnostics.rst, utils.rst: 1 each Residual after this PR: 635 warnings (down from 2,170). Of these: - 614 `duplicate object description` warnings remain at the MEMBER level (e.g., `BaconDecomposition.__init__` registered by both the stub's autoclass and the page-level autoclass's autodoc-injected `:members:` rendering). Sphinx's `:no-index:` on autoclass does NOT propagate to autodoc-generated member entries, so members are re-registered despite the class itself being suppressed. Resolving these requires either a custom autosummary template OR adding `:no-members:` to page-level autoclass directives (UX impact: page-level no longer shows inline member docs). Deferred to a separate PR with a fresh architectural decision. - 21 non-duplicate residuals (4 `unknown document: '../methodology/REPORTING'` cross-refs; 3 `EDiDBootstrapResults` cross-ref ambiguities; ~14 misc autosummary import failures and unindented-text warnings). Each needs individual triage before `-W` enforcement (PR 3) can land. Verification: - `make html`: 0 errors, 635 warnings (was 2,170; baseline duplicate- object class dropped from 2,146 to 614; no new warning categories). - `pytest tests/test_doc_snippets.py`: 111 passed, 4 skipped (Batch C / PR 1 baseline unchanged). - HTML rendering preserved: page-level pages still show member docs; cross-refs resolve to stubs (DiDResults.att HTML id present in `_autosummary/diff_diff.DiDResults.html`, absent from `api/results.html` as `:no-index:` intends). - 0 em-dashes in diff. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Overall Assessment: ✅ Looks GoodExecutive Summary
MethodologyFinding: None
Code QualityFinding: None
PerformanceFinding: None
MaintainabilityFinding: No unmirrored page-level
Tech DebtFinding: Residual Sphinx warning cleanup remains tracked
SecurityFinding: None
Documentation/TestsFinding: Static review only; build/test claims not independently rerun
|
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.
Summary
PR 2 of the 2-PR Sphinx cleanup sequence (PR 1 = #405, landed
ec1de01). Dropsmake htmlwarning count from 2,170 to 635(71% reduction; 1,535 fewer warnings) by suppressing class-level
cross-reference duplicate registrations between page-level RST
files and autosummary stubs.
Sphinx itself recommends
:no-index:for the duplicating side (perthe warning text). Architecture:
docs/api/*.rst(78 sitesacross 23 files) get
:no-index:docs/api/_autosummary/*.rstremaincanonical for cross-references (
:class:\DiDResults`` andsimilar resolve to stub pages)
change to RST users); only the global cross-reference inventory
is affected by
:no-index:Approach validated empirically before the global pass via spike
on
bacon.rst(3 directives): all 19 baseline duplicates citingapi/baconcleared (100% drop on the spike's local scope), 0errors, all rendered HTML members preserved. Spike pass criteria
met; global pass applied via single
sedinvocation per file.Methodology references
N/A - all changes are RST directive-option additions. No estimator
logic, defaults, weighting, or inference behavior changed.
Validation
make html: 0 errors, 635 warnings (was 2,170; baselineduplicate-object class dropped from 2,146 to 614). Critical
point: no new warning categories introduced (5 apparent diffs
vs PR 1 baseline are sort-uniq false positives — same counts in
both builds).
pytest tests/test_doc_snippets.py: 111 passed, 4 skipped (BatchC / PR 1 baseline unchanged).
docs (281
<dt>tags inresults.html); cross-refs resolve tostubs (
DiDResults.attHTML id present in_autosummary/diff_diff.DiDResults.html, absent fromapi/results.htmlas:no-index:intends).Honest accounting on the residual 635 warnings
This PR achieves a 71% reduction, NOT the originally hoped-for ~99%.
The residual breakdown:
duplicate object descriptionwarnings at the MEMBERlevel (e.g.,
BaconDecomposition.__init__registered by both thestub's autoclass and the page-level autoclass's autodoc-injected
:members:rendering). Sphinx's:no-index:onautoclassdoesNOT propagate to autodoc-generated member entries — only the
class itself is suppressed. Resolving these requires either a
custom autosummary template OR
:no-members:on page-levelautoclass (UX impact: page-level pages no longer show inline
member docs). Deferred to a separate PR with a fresh
architectural decision.
unknown document: '../methodology/REPORTING'cross-refs; 3EDiDBootstrapResultscross-ref ambiguities; ~14 misc autosummary import failures and
unindented-text warnings. Each needs individual triage before
-Wenforcement (PR 3) can land.Out of scope (queued)
:members:from generated stubs, OR add:no-members:to page-level autoclass directives (and accept the UX shift to clicking into stubs for member details). Architectural choice worth its own plan + review. Resolves the remaining 614 duplicates.-Wtodocs-tests.ymlbuildunknown document: '../methodology/REPORTING'warningsbusiness_report.rst:48,52anddiagnostic_report.rst:14,18link to a doc that doesn't exist on this branch. Either fix the link or suppress. PR 3 prerequisite.EDiDBootstrapResultscross-ref ambiguitiesSecurity / privacy
Generated with Claude Code