igerber · igerber · Jul 19, 2026 · Jul 19, 2026 · Jul 19, 2026 · Jul 19, 2026
@@ -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.

diff --git a/.readthedocs.yaml b/.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:

diff --git a/CHANGELOG.md b/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

diff --git a/CLAUDE.md b/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.
 

diff --git a/CONTRIBUTING.md b/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)

diff --git a/docs/api/_autosummary/diff_diff.BaconDecompositionResults.rst b/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

diff --git a/docs/api/_autosummary/diff_diff.CSBootstrapResults.rst b/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

diff --git a/docs/api/_autosummary/diff_diff.CallawaySantAnnaResults.rst b/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

diff --git a/docs/api/_autosummary/diff_diff.ChangesInChanges.rst b/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
+
+
+
+
diff --git a/docs/api/_autosummary/diff_diff.ContinuousDiDResults.rst b/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

diff --git a/docs/api/_autosummary/diff_diff.DiDResults.rst b/docs/api/_autosummary/diff_diff.DiDResults.rst
@@ -30,11 +30,14 @@
       ~DiDResults.coef_var
       ~DiDResults.coefficients
       ~DiDResults.conley_lag_cutoff
+      ~DiDResults.df_convention
       ~DiDResults.fitted_values
+      ~DiDResults.inference_df
       ~DiDResults.inference_method
       ~DiDResults.is_significant
       ~DiDResults.n_bootstrap
       ~DiDResults.n_clusters
+      ~DiDResults.p_val_type
       ~DiDResults.r_squared
       ~DiDResults.residuals
       ~DiDResults.significance_stars

diff --git a/docs/api/_autosummary/diff_diff.EfficientDiDResults.rst b/docs/api/_autosummary/diff_diff.EfficientDiDResults.rst
@@ -43,6 +43,7 @@
       ~EfficientDiDResults.n_bootstrap
       ~EfficientDiDResults.n_clusters
       ~EfficientDiDResults.omega_condition_numbers
+      ~EfficientDiDResults.omega_ridge
       ~EfficientDiDResults.p_value
       ~EfficientDiDResults.pt_assumption
       ~EfficientDiDResults.ratio_clip

diff --git a/docs/api/_autosummary/diff_diff.GroupTimeEffect.rst b/docs/api/_autosummary/diff_diff.GroupTimeEffect.rst
@@ -22,6 +22,7 @@
 
       ~GroupTimeEffect.is_significant
       ~GroupTimeEffect.significance_stars
+      ~GroupTimeEffect.skip_reason
       ~GroupTimeEffect.group
       ~GroupTimeEffect.time
       ~GroupTimeEffect.effect

diff --git a/docs/api/_autosummary/diff_diff.ImputationDiDResults.rst b/docs/api/_autosummary/diff_diff.ImputationDiDResults.rst
@@ -16,6 +16,7 @@
       ~ImputationDiDResults.print_summary
       ~ImputationDiDResults.summary
       ~ImputationDiDResults.to_dataframe
+      ~ImputationDiDResults.to_dict
 
 
 
@@ -28,15 +29,19 @@
       ~ImputationDiDResults.anticipation
       ~ImputationDiDResults.att
       ~ImputationDiDResults.bootstrap_results
+      ~ImputationDiDResults.cluster_name
       ~ImputationDiDResults.coef_var
       ~ImputationDiDResults.conf_int
       ~ImputationDiDResults.is_significant
+      ~ImputationDiDResults.leave_one_out
+      ~ImputationDiDResults.n_clusters
       ~ImputationDiDResults.p_value
       ~ImputationDiDResults.pretrend_results
       ~ImputationDiDResults.se
       ~ImputationDiDResults.significance_stars
       ~ImputationDiDResults.survey_metadata
       ~ImputationDiDResults.t_stat
+      ~ImputationDiDResults.vcov_type
       ~ImputationDiDResults.treatment_effects
       ~ImputationDiDResults.overall_att
       ~ImputationDiDResults.overall_se

diff --git a/docs/api/_autosummary/diff_diff.MultiPeriodDiDResults.rst b/docs/api/_autosummary/diff_diff.MultiPeriodDiDResults.rst
@@ -32,7 +32,9 @@
       ~MultiPeriodDiDResults.coefficients
       ~MultiPeriodDiDResults.conf_int
       ~MultiPeriodDiDResults.conley_lag_cutoff
+      ~MultiPeriodDiDResults.df_convention
       ~MultiPeriodDiDResults.fitted_values
+      ~MultiPeriodDiDResults.inference_df
       ~MultiPeriodDiDResults.inference_method
       ~MultiPeriodDiDResults.interaction_indices
       ~MultiPeriodDiDResults.is_significant

diff --git a/docs/api/_autosummary/diff_diff.PreTrendsPowerCurve.rst b/docs/api/_autosummary/diff_diff.PreTrendsPowerCurve.rst
@@ -22,11 +22,11 @@
 
    .. autosummary::
 
+      ~PreTrendsPowerCurve.pretest_form
       ~PreTrendsPowerCurve.M_values
       ~PreTrendsPowerCurve.powers
       ~PreTrendsPowerCurve.mdv
       ~PreTrendsPowerCurve.alpha
       ~PreTrendsPowerCurve.target_power
       ~PreTrendsPowerCurve.violation_type
-      ~PreTrendsPowerCurve.pretest_form
 
diff --git a/docs/api/_autosummary/diff_diff.PreTrendsPowerResults.rst b/docs/api/_autosummary/diff_diff.PreTrendsPowerResults.rst
@@ -25,10 +25,14 @@
 
    .. autosummary::
 
+      ~PreTrendsPowerResults.covariance_source
       ~PreTrendsPowerResults.is_informative
       ~PreTrendsPowerResults.max_abs_pre_violation
+      ~PreTrendsPowerResults.nis_box_probability
       ~PreTrendsPowerResults.original_results
       ~PreTrendsPowerResults.power_adequate
+      ~PreTrendsPowerResults.pretest_form
+      ~PreTrendsPowerResults.violation_weights
       ~PreTrendsPowerResults.power
       ~PreTrendsPowerResults.mdv
       ~PreTrendsPowerResults.violation_magnitude
@@ -42,8 +46,4 @@
       ~PreTrendsPowerResults.pre_period_effects
       ~PreTrendsPowerResults.pre_period_ses
       ~PreTrendsPowerResults.vcov
-      ~PreTrendsPowerResults.pretest_form
-      ~PreTrendsPowerResults.nis_box_probability
-      ~PreTrendsPowerResults.violation_weights
-      ~PreTrendsPowerResults.covariance_source
 
diff --git a/docs/api/_autosummary/diff_diff.QDiD.rst b/docs/api/_autosummary/diff_diff.QDiD.rst
@@ -0,0 +1,21 @@
+diff\_diff.QDiD
+===============
+
+.. currentmodule:: diff_diff
+
+.. autoclass:: QDiD
+   :no-members:
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~QDiD.__init__
+      ~QDiD.fit
+      ~QDiD.get_params
+      ~QDiD.set_params
+
+
+
+
diff --git a/docs/api/_autosummary/diff_diff.RDPlot.rst b/docs/api/_autosummary/diff_diff.RDPlot.rst
@@ -0,0 +1,21 @@
+diff\_diff.RDPlot
+=================
+
+.. currentmodule:: diff_diff
+
+.. autoclass:: RDPlot
+   :no-members:
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~RDPlot.__init__
+      ~RDPlot.fit
+      ~RDPlot.get_params
+      ~RDPlot.set_params
+
+
+
+
diff --git a/docs/api/_autosummary/diff_diff.RDPlotResult.rst b/docs/api/_autosummary/diff_diff.RDPlotResult.rst
@@ -0,0 +1,49 @@
+diff\_diff.RDPlotResult
+=======================
+
+.. currentmodule:: diff_diff
+
+.. autoclass:: RDPlotResult
+   :no-members:
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~RDPlotResult.__init__
+      ~RDPlotResult.plot
+      ~RDPlotResult.summary
+      ~RDPlotResult.to_dataframe
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~RDPlotResult.covariate_coefficients
+      ~RDPlotResult.covariates_dropped
+      ~RDPlotResult.wimse_bias_weight
+      ~RDPlotResult.wimse_variance_weight
+      ~RDPlotResult.coef
+      ~RDPlotResult.vars_bins
+      ~RDPlotResult.vars_poly
+      ~RDPlotResult.J
+      ~RDPlotResult.J_IMSE
+      ~RDPlotResult.J_MV
+      ~RDPlotResult.scale
+      ~RDPlotResult.rscale
+      ~RDPlotResult.bin_avg
+      ~RDPlotResult.bin_med
+      ~RDPlotResult.p
+      ~RDPlotResult.cutoff
+      ~RDPlotResult.h
+      ~RDPlotResult.N
+      ~RDPlotResult.N_h
+      ~RDPlotResult.binselect
+      ~RDPlotResult.kernel_type
+      ~RDPlotResult.ci_level
+      ~RDPlotResult.ci_requested
+
diff --git a/docs/api/_autosummary/diff_diff.RegressionDiscontinuity.rst b/docs/api/_autosummary/diff_diff.RegressionDiscontinuity.rst
@@ -0,0 +1,21 @@
+diff\_diff.RegressionDiscontinuity
+==================================
+
+.. currentmodule:: diff_diff
+
+.. autoclass:: RegressionDiscontinuity
+   :no-members:
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~RegressionDiscontinuity.__init__
+      ~RegressionDiscontinuity.fit
+      ~RegressionDiscontinuity.get_params
+      ~RegressionDiscontinuity.set_params
+
+
+
+