docs: restructure RTD site around 5 top-level sections (IA overhaul)

[igerber]

Summary

• Replace the 40-entry flat root toctree with 5 top-level sections (Getting Started / Practitioner Guide / Tutorials / User Guide / API Reference), each with a sphinx-design card-grid landing page. The old structure flattened into pydata-sphinx-theme's header as a 34-item "More" dropdown that was taller than a 900px viewport (bottom items, including API Reference, unclickable) and a 45-link unsectioned mobile menu.

• New docs/tutorials/index.rst groups all 28 notebooks into 4 tracks (Business Applications / Fundamentals / Advanced Methods / Study Design) with short sidebar labels and per-notebook cards - tutorial pages get sibling navigation in the left sidebar for the first time, and prev/next now follows a coherent grouped order.

• Homepage: "Explore the Documentation" card grid, full-width layout (html_sidebars = {"index": []}), html_title shortened to "diff-diff documentation" for SERP/tab display.

• docs/quickstart.rst H1 "Getting Started" -> "Quickstart" (resolves a three-way "Getting Started" label collision).

• sphinx-design>=0.6.1 added to the four synced dependency surfaces (pyproject docs extra, .readthedocs.yaml, both docs-tests.yml pip lines). Floor deliberately 0.6.1: sphinx-design 0.7.0 requires Python >=3.11 and would break the docs-deps-py39-smoke job.

• New-tutorial registration convention (toctree entry + card in docs/tutorials/index.rst, not docs/index.rst) documented in CONTRIBUTING.md and CLAUDE.md; CHANGELOG bullet added.

• URL stability: no existing .rst/.ipynb file moves or renames - all deep links in README, diff_diff/guides/llms*.txt, and external consumers keep working. Landing pages are additive.

• Drift sync (second commit): homepage "Supported Estimators" table refreshed from 15 stale rows to the full 23-entry current catalog ("13+" claims -> "20+"); RDD classes (RegressionDiscontinuity, results, RDPlot) added to the api/index.rst autosummary - they were documented only with :no-index: on the module page, so :class: cross-references to them rendered as dead text; checked-in api/_autosummary stubs refreshed to match current source (they had drifted - missing new result attributes and three never-committed CiC/QDiD stubs).

Methodology references (required if estimator / math changes)

• Method name(s): N/A - no methodology changes (documentation navigation/structure only)
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None

Validation

• Tests added/updated: No test changes. tests/test_doc_snippets.py passes (119 passed, 5 skipped); the homepage code snippet is byte-identical.
• Backtest / simulation / notebook evidence (if applicable): Local make -C docs html SPHINXOPTS="-W" builds with zero warnings on the CI dependency set. Browser-verified on the built HTML at 1440px and 390px: navbar shows exactly 5 links (no "More" dropdown), tutorial pages show the 4 grouped tracks in the left sidebar, mobile menu shows 5 sections instead of 45 flat links, choosing_estimator.html#survey-design-support and api/staggered.html#staggeredtripledifference anchors preserved, stable URLs (quickstart.html, tutorials/*.html) unchanged.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall Assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive Summary

• No estimator, identification, weighting, variance, SE, or default behavior changes.
• Method descriptions align with the Methodology Registry and existing tutorials.
• All 28 notebooks and new card/toctree targets exist.
• Documentation dependencies are synchronized across declared installation surfaces.
• One P2 URL-fragment compatibility issue remains.

Methodology

No findings. No causal methods are affected.

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings.

Tech Debt

No findings.

Security

No findings or exposed secrets detected.

Documentation/Tests

P2 — Legacy Quickstart fragment is no longer preserved

• Location: docs/quickstart.rst:L5-L6
• Impact: Renaming the heading from “Getting Started” to “Quickstart” changes its generated HTML fragment from #getting-started to #quickstart. Existing deep links to quickstart.html#getting-started will no longer resolve to the heading.
• Concrete fix: Add .. _getting-started: immediately before the new heading, preserving the legacy fragment while retaining the new title.

Local Sphinx and pytest execution was unavailable because those tools are not installed in the review environment.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 88e2e364e49c3bea969634b51115d6a008141c18

---

Overall Assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive Summary

• No estimator logic, assumptions, weighting, variance, SE, or defaults changed.
• New methodological summaries agree with the Methodology Registry and source docstrings.
• All 28 tutorial cards and toctree targets exist.
• The previous P2 fragment-compatibility finding remains unresolved.
• The refreshed estimator catalog omits QDiD.

Methodology

No findings. The affected documentation descriptions align with docs/methodology/REGISTRY.md and cited references.

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings. The new dependency is synchronized across all four declared documentation environments.

Tech Debt

No findings or relevant tracked limitations.

Security

No findings or exposed secrets detected.

Documentation/Tests

P2 — Legacy Quickstart fragment remains broken

• Location: docs/quickstart.rst:L5-L6
• Impact: Renaming the heading changes quickstart.html#getting-started to #quickstart, breaking existing fragment links.
• Concrete fix: Add .. _getting-started: immediately before the Quickstart heading.

P2 — Refreshed estimator catalog omits QDiD

• Location: docs/index.rst:L174-L177; docs/api/index.rst:L34-L35
• Impact: The homepage catalog remains incomplete despite QDiD being a supported, documented top-level estimator.
• Concrete fix: Add a QDiD row beside ChangesInChanges, describing it as the quantile-DiD comparison estimator.

A Sphinx build could not be run because the review environment lacks Sphinx and its Python dependencies.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: fca43887a5e67f7e9a0134e75e3d2e293abf814d

---

Overall Assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive Summary

• No estimator logic, assumptions, weighting, variance, inference, or defaults changed.
• New estimator descriptions align with the Methodology Registry and source docstrings.
• All 28 tutorial cards and toctree targets resolve to existing notebooks.
• Both previously reported P2 documentation findings remain unresolved.
• Sphinx could not be run because the review environment lacks documentation dependencies.

Methodology

No findings. The refreshed summaries, including RDD, CiC, HAD, LP-DiD, and Wooldridge ETWFE, agree with docs/methodology/REGISTRY.md.

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings. sphinx-design is synchronized across all four documentation dependency surfaces.

Tech Debt

No findings.

Security

No findings. No exposed secrets or credentials detected.

Documentation/Tests

P2 — Legacy Quickstart fragment remains broken

• Status: Previously reported, unresolved
• Location: docs/quickstart.rst:L5-L6
• Impact: Renaming the heading removes quickstart.html#getting-started, breaking existing bookmarked or external fragment links.
• Concrete fix: Add .. _getting-started: immediately before the Quickstart heading.

P2 — Homepage estimator catalog still omits QDiD

• Status: Previously reported, unresolved
• Location: docs/index.rst:L174-L177
• Impact: The refreshed catalog remains incomplete despite QDiD being a supported public estimator with its own API entry.
• Concrete fix: Add a QDiD row describing it as the Athey–Imbens quantile-DiD comparison estimator.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 466b27d03c9735a76e374acc1fe1441ab3098be6

---

Overall Assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive Summary

• No estimator logic, inference, assumptions, weighting, or defaults changed.
• Method descriptions agree with docs/methodology/REGISTRY.md.
• All 28 tutorial cards and toctree entries resolve correctly.
• Both previously reported P2 documentation issues remain unresolved.
• Tests could not be rerun because the review environment lacks project/docs dependencies.

Methodology

No findings. The refreshed estimator summaries and RDD taxonomy match the Methodology Registry and source APIs.

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings. sphinx-design is synchronized across all four dependency surfaces.

Tech Debt

No findings.

Security

No findings. No credentials or secrets detected.

Documentation/Tests

P2 — Legacy Quickstart fragment remains broken

• Status: Previously reported, unresolved
• Location: docs/quickstart.rst:L5-L6
• Impact: Renaming the heading removes the existing quickstart.html#getting-started fragment.
• Concrete fix: Add .. _getting-started: immediately before the Quickstart heading.

P2 — Homepage catalog still omits QDiD

• Status: Previously reported, unresolved
• Location: docs/index.rst:L174-L177
• Impact: The homepage catalog is incomplete: QDiD remains a supported public estimator listed in the API reference and Methodology Registry.
• Concrete fix: Add a QDiD row describing it as the Athey–Imbens quantile-DiD comparison estimator.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 15f361b1ade6018586afa4146b89a8fb93cabefd

---

Overall Assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive Summary

• No estimator, inference, weighting, variance, assumptions, or defaults changed.
• New estimator descriptions align with the Methodology Registry and source docstrings.
• Both previous P2 findings are resolved.
• All 28 tutorials have matching cards, toctree entries, and source notebooks.
• Added autosummary symbols and documentation links resolve statically.

Methodology

No findings. Documentation claims for RD, QDiD, CiC, HAD, Continuous DiD, and other listed methods match docs/methodology/REGISTRY.md.

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings. sphinx-design>=0.6.1 is synchronized across all four dependency surfaces.

Tech Debt

No findings.

Security

No findings. No apparent secrets or credentials were introduced.

Documentation/Tests

No findings.

• Resolved: The legacy Quickstart fragment is preserved by .. _getting-started: at docs/quickstart.rst:L5.
• Resolved: QDiD now appears in the homepage estimator catalog at docs/index.rst:L176-L177.
• All landing-page links and all 28 tutorial card/toctree pairs resolve.
• Full Sphinx and pytest runs were unavailable because the review environment lacks the project and documentation dependencies.