test: CI-enforced docs IA guards (tests/test_docs_ia.py)

[igerber]

Summary

• Adds tests/test_docs_ia.py: structural guards for the docs: restructure RTD site around 5 top-level sections (IA overhaul) #703 documentation information architecture, covering four invariants that are all valid-Sphinx states the -W build cannot catch: (1) the root docs/index.rst toctree stays exactly the 5 section landing pages (a 6th entry regrows the navbar "More" dropdown); (2) every tutorial notebook is registered in docs/tutorials/index.rst with BOTH a short-labeled toctree entry (<= 40 chars) and a grid card, in the same group, with whole-file duplicate counting; (3) the homepage "Supported Estimators" table stays 1:1 with the api/index.rst Estimators autosummary, compared by object identity (same-named distinct classes cannot satisfy parity; submodule/re-export aliases match); (4) no class is documented only under :no-index: - the dead-cross-reference failure mode the RDD classes had before docs: restructure RTD site around 5 top-level sections (IA overhaul) #703 - including committed class stubs.
• Parsers are deliberately directive-scoped (contiguous option blocks, :toctree:-gated autosummary bodies, module-shadow-aware qualname resolution - diff_diff.trop the package attribute is a function that shadows the module) with a negative fixture per failure shape; the module docstring bounds scope to the RST conventions this repo actually uses. Each invariant was mutation-verified against a seeded violation.
• CI wiring: new step in the docs-tests doc-snippets job plus tests/test_docs_ia.py path triggers; the suite skips cleanly on isolated-install CI (no docs tree).
• Conventions documented for humans and agents: CONTRIBUTING.md gains a "Docs IA invariants" section, CLAUDE.md the registration + :no-index: rules, /docs-check a runnable 5b section, and CHANGELOG an internal bullet.

Methodology references (required if estimator / math changes)

• Method name(s): N/A - documentation-infrastructure tests only
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None

Validation

• Tests added/updated: tests/test_docs_ia.py (18 tests: 5 live invariants + 13 parser/negative fixtures), all passing; each invariant mutation-verified (seeded violations fail with actionable messages).
• Backtest / simulation / notebook evidence (if applicable): N/A - no runtime code paths touched.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall assessment: ✅ Looks good

Executive summary

• No P0/P1 findings.
• No estimator, inference, variance, weighting, assumptions, or defaults changed.
• IA parsers match the repository’s current RST conventions and 28 tutorials.
• No security or performance concerns found.
• Full pytest execution was unavailable because dependencies are absent; syntax and 13 dependency-free tests passed via a local harness.

Methodology

• Severity: N/A
  Impact: No causal methods are affected; Registry or paper reconciliation is unnecessary.
  Concrete fix: None.

Code Quality

• Severity: N/A
  Impact: Parsers are scoped, readable, and have targeted negative fixtures.
  Concrete fix: None.

Performance

• Severity: N/A
  Impact: Repository-sized RST scans and cached imports are inexpensive.
  Concrete fix: None.

Maintainability

• Severity: N/A
  Impact: Constants and documented parser boundaries make intended changes clear.
  Concrete fix: None.

Tech Debt

• Severity: N/A
  Impact: No new untracked limitation identified.
  Concrete fix: None.

Security

• Severity: N/A
  Impact: No secrets, unsafe execution, or untrusted-input exposure found.
  Concrete fix: None.

Documentation/Tests

• Severity: N/A
  Impact: CI wiring and contributor guidance consistently describe the enforced invariants.
  Concrete fix: None.