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

Author: igerber

.github/workflows/docs-tests.yml

@@ -118,7 +118,7 @@ jobs:
         # docs/conf.py imports diff_diff via sys.path from checked-out source.
         # ipython provides the 'ipython3' Pygments lexer that nbsphinx uses
         # for notebook code cells; without it -W fires highlighting_failure.
-        run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.10" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "myst-parser>=2.0" "matplotlib>=3.5" "ipython>=8.0"
+        run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.10" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "myst-parser>=2.0" "sphinx-design>=0.6.1" "matplotlib>=3.5" "ipython>=8.0"
 
       - name: Build docs with warnings as errors
         # SPHINXOPTS="-W" turns every Sphinx warning into a build failure.
@@ -154,7 +154,7 @@ jobs:
         # not run a Sphinx build (sphinx-build covers full rendering on 3.11).
         # Failure here means the docs floor declared in pyproject.toml /
         # .readthedocs.yaml / above is not installable on Python 3.9.
-        run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.10" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "myst-parser>=2.0" "matplotlib>=3.5" "ipython>=8.0"
+        run: pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.10" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "myst-parser>=2.0" "sphinx-design>=0.6.1" "matplotlib>=3.5" "ipython>=8.0"
 
       - name: Confirm pydata-sphinx-theme version
         # Surface the resolved version in the log for future debugging.

.readthedocs.yaml

@@ -18,7 +18,7 @@ build:
       #
       # Keep in sync with pyproject.toml [project.dependencies]
       # and [project.optional-dependencies.docs].
-      - pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.10" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "myst-parser>=2.0" "matplotlib>=3.5" "ipython>=8.0"
+      - pip install "numpy>=1.20.0" "pandas>=1.3.0" "scipy>=1.10" "sphinx>=6.0" "pydata-sphinx-theme>=0.16.1" "sphinxext-opengraph>=0.9" "sphinx-sitemap>=2.5" "nbsphinx>=0.9" "myst-parser>=2.0" "sphinx-design>=0.6.1" "matplotlib>=3.5" "ipython>=8.0"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

CHANGELOG.md

@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- **Documentation site restructured around 5 top-level sections** (Getting Started /
+  Practitioner Guide / Tutorials / User Guide / API Reference). The previous flat
+  navigation put 40 pages into the pydata-sphinx-theme header, leaving most of the
+  site (including the API reference) reachable only through an oversized "More"
+  dropdown; the navbar now shows exactly the 5 sections, each with a card-grid
+  landing page (new `sphinx-design` docs dependency). Tutorials get a grouped index
+  at `tutorials/index.html` with short sidebar labels, and tutorial pages now show
+  their sibling notebooks in the left sidebar. All existing page URLs are unchanged.
 - **Internal: dev tooling pins bumped** (Dependabot group + manual lint.yml sync):
   `black==26.5.1`, `ruff==0.15.21`, `mypy==2.3.0` in both the `dev` extra and the
   Lint CI workflow. mypy >= 2.2 can no longer target Python 3.9, so

CLAUDE.md

@@ -149,7 +149,10 @@ When adding new functionality, the source of truth is:
 - **`diff_diff/guides/llms.txt`** for the AI-agent contract (one-line catalog entry per estimator with paper citation + RTD link). This file is bundled in the wheel and published on RTD via `docs/conf.py` `html_extra_path`.
 - **`docs/api/*.rst`** for full API reference.
 - **`docs/references.rst`** for scholarly citations.
-- **`docs/tutorials/*.ipynb`** for hands-on examples.
+- **`docs/tutorials/*.ipynb`** for hands-on examples. New notebooks are registered in
+  `docs/tutorials/index.rst` (toctree entry with a short display label + a card in the
+  matching group), NOT in `docs/index.rst` - the root toctree lists only the 5 section
+  landing pages so the navbar stays at 5 links.
 - **`CHANGELOG.md`** for release notes.
 - **`README.md`** for ONE LINE in the `## Estimators` flat catalog (or `## Diagnostics & Sensitivity` for diagnostic-class features). Do NOT add usage examples, parameter tables, per-estimator sections, or full bibliographies.
 

CONTRIBUTING.md

@@ -61,6 +61,10 @@ If you find yourself adding a usage example, a parameter table, or a multi-parag
 3. **`docs/tutorials/*.ipynb`** - Update relevant tutorial or create new one:
    - Working code examples
    - Explanation of when/why to use the feature
+   - New notebooks are registered in `docs/tutorials/index.rst` (NOT `docs/index.rst`):
+     add a toctree entry with a short display label to the matching group
+     (Business Applications / Fundamentals / Advanced Methods / Study Design)
+     plus a `grid-item-card` in that group's card grid
 
 4. **`docs/references.rst`** (bibliography source of truth) - Add:
    - Full citation under the appropriate sub-section (matches the `### Subsection` headings already in that file)

docs/api/_autosummary/diff_diff.BaconDecompositionResults.rst

@@ -26,6 +26,7 @@
    .. autosummary::
 
       ~BaconDecompositionResults.decomposition_error
+      ~BaconDecompositionResults.n_always_treated_remapped
       ~BaconDecompositionResults.n_obs
       ~BaconDecompositionResults.survey_metadata
       ~BaconDecompositionResults.twfe_estimate

docs/api/_autosummary/diff_diff.CSBootstrapResults.rst

@@ -28,15 +28,15 @@
       ~CSBootstrapResults.group_effect_cis
       ~CSBootstrapResults.group_effect_p_values
       ~CSBootstrapResults.group_effect_ses
+      ~CSBootstrapResults.overall_att_es_ci
+      ~CSBootstrapResults.overall_att_es_p_value
+      ~CSBootstrapResults.overall_att_es_se
       ~CSBootstrapResults.n_bootstrap
       ~CSBootstrapResults.weight_type
       ~CSBootstrapResults.alpha
       ~CSBootstrapResults.overall_att_se
       ~CSBootstrapResults.overall_att_ci
       ~CSBootstrapResults.overall_att_p_value
-      ~CSBootstrapResults.overall_att_es_se
-      ~CSBootstrapResults.overall_att_es_ci
-      ~CSBootstrapResults.overall_att_es_p_value
       ~CSBootstrapResults.group_time_ses
       ~CSBootstrapResults.group_time_cis
       ~CSBootstrapResults.group_time_p_values

docs/api/_autosummary/diff_diff.CallawaySantAnnaResults.rst

@@ -24,15 +24,18 @@
 
    .. autosummary::
 
+      ~CallawaySantAnnaResults.allow_unbalanced_panel
       ~CallawaySantAnnaResults.alpha
       ~CallawaySantAnnaResults.anticipation
       ~CallawaySantAnnaResults.att
       ~CallawaySantAnnaResults.base_period
       ~CallawaySantAnnaResults.bootstrap_results
       ~CallawaySantAnnaResults.cband_crit_value
+      ~CallawaySantAnnaResults.cluster_name
       ~CallawaySantAnnaResults.coef_var
       ~CallawaySantAnnaResults.conf_int
       ~CallawaySantAnnaResults.control_group
+      ~CallawaySantAnnaResults.df_inference
       ~CallawaySantAnnaResults.epv_diagnostics
       ~CallawaySantAnnaResults.epv_threshold
       ~CallawaySantAnnaResults.event_study_effects
@@ -41,6 +44,7 @@
       ~CallawaySantAnnaResults.group_effects
       ~CallawaySantAnnaResults.influence_functions
       ~CallawaySantAnnaResults.is_significant
+      ~CallawaySantAnnaResults.n_clusters
       ~CallawaySantAnnaResults.p_value
       ~CallawaySantAnnaResults.panel
       ~CallawaySantAnnaResults.pscore_fallback
@@ -49,6 +53,8 @@
       ~CallawaySantAnnaResults.significance_stars
       ~CallawaySantAnnaResults.survey_metadata
       ~CallawaySantAnnaResults.t_stat
+      ~CallawaySantAnnaResults.used_rc_on_unbalanced_panel
+      ~CallawaySantAnnaResults.vcov_type
       ~CallawaySantAnnaResults.group_time_effects
       ~CallawaySantAnnaResults.overall_att
       ~CallawaySantAnnaResults.overall_se

docs/api/_autosummary/diff_diff.ChangesInChanges.rst

@@ -0,0 +1,21 @@
+diff\_diff.ChangesInChanges
+===========================
+
+.. currentmodule:: diff_diff
+
+.. autoclass:: ChangesInChanges
+   :no-members:
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ChangesInChanges.__init__
+      ~ChangesInChanges.fit
+      ~ChangesInChanges.get_params
+      ~ChangesInChanges.set_params
+
+
+
+

docs/api/_autosummary/diff_diff.ContinuousDiDResults.rst

@@ -31,7 +31,10 @@
       ~ContinuousDiDResults.coef_var
       ~ContinuousDiDResults.conf_int
       ~ContinuousDiDResults.control_group
+      ~ContinuousDiDResults.covariates
       ~ContinuousDiDResults.degree
+      ~ContinuousDiDResults.epv_threshold
+      ~ContinuousDiDResults.estimation_method
       ~ContinuousDiDResults.event_study_effects
       ~ContinuousDiDResults.is_significant
       ~ContinuousDiDResults.n_bootstrap
@@ -41,12 +44,16 @@
       ~ContinuousDiDResults.overall_se
       ~ContinuousDiDResults.overall_t_stat
       ~ContinuousDiDResults.p_value
+      ~ContinuousDiDResults.pscore_fallback
+      ~ContinuousDiDResults.pscore_trim
       ~ContinuousDiDResults.rank_deficient_action
+      ~ContinuousDiDResults.reference_dose
       ~ContinuousDiDResults.se
       ~ContinuousDiDResults.seed
       ~ContinuousDiDResults.significance_stars
       ~ContinuousDiDResults.survey_metadata
       ~ContinuousDiDResults.t_stat
+      ~ContinuousDiDResults.treatment_type
       ~ContinuousDiDResults.dose_response_att
       ~ContinuousDiDResults.dose_response_acrt
       ~ContinuousDiDResults.overall_att