Merge pull request #410 from igerber/docs/sphinx-member-duplicate-fix

docs: custom autosummary template + residual triage (PR 2.5)

Author: igerber

TODO.md

@@ -131,12 +131,8 @@ Deferred items from PR reviews that were not addressed before merge.
 |-------|----------|----|----------|
 | R comparison tests spawn separate `Rscript` per test (slow CI) | `tests/test_methodology_twfe.py:294` | #139 | Low |
 | CS R helpers hard-code `xformla = ~ 1`; no covariate-adjusted R benchmark for IRLS path | `tests/test_methodology_callaway.py` | #202 | Low |
-| ~1583 `duplicate object description` Sphinx warnings — restructure `docs/api/*.rst` to avoid duplicate `:members:` + `autosummary` (count grew from ~376 as API surface expanded) | `docs/api/*.rst` | — | Low |
 | Doc-snippet smoke tests only cover `.rst` files; `.txt` AI guides outside CI validation | `tests/test_doc_snippets.py` | #239 | Low |
 | Add CI validation for `docs/doc-deps.yaml` integrity (stale paths, unmapped source files) | `docs/doc-deps.yaml` | #269 | Low |
-| Sphinx autodoc fails to import 3 result members: `DiDResults.ci`, `MultiPeriodDiDResults.att`, `CallawaySantAnnaResults.aggregate` — investigate whether these are renamed/removed or just unresolvable from autosummary template | `docs/api/results.rst`, `docs/api/staggered.rst` | — | Medium |
-| `EDiDBootstrapResults` cross-reference is ambiguous — class is exported from both `diff_diff` and `diff_diff.efficient_did_bootstrap`, producing 3 "more than one target found" warnings. Add `:noindex:` to one source or use full-path refs | `diff_diff/efficient_did_results.py`, `docs/api/efficient_did.rst` | — | Low |
-| Tracked Sphinx autosummary stubs in `docs/api/_autosummary/*.rst` are stale — every sphinx build regenerates them with new attributes (e.g., `coef_var`, `survey_metadata`) that have been added to result classes. Either commit a refresh or move the directory to `.gitignore` and treat as build output. Also 6 untracked stubs exist for newer estimators (`WooldridgeDiD`, `SimulationMDEResults`, etc.) that have never been committed. | `docs/api/_autosummary/` | — | Low |
 | HonestDiD `test_m0_short_circuit` uses wall-clock `elapsed < 0.5s` as a proxy for "short-circuit path taken" instead of calling the full optimizer. Replace with a direct correctness signal (mock/spy the optimizer or check a state flag) so the test doesn't depend on CI timing. Not flaky today at 500ms, but load-bearing correctness on a timing proxy is brittle. | `tests/test_methodology_honest_did.py:246` | — | Low |
 | SyntheticDiD: rename internal `placebo_effects` variable to `variance_effects` (or `resampled_effects`). Misleading name across the placebo/bootstrap/jackknife dispatch paths — holds three different contents depending on variance method. Low-risk refactor; user-facing field rename should preserve `placebo_effects` as a deprecated alias for one release. | `synthetic_did.py`, `results.py` | follow-up | Medium |
 

diff_diff/results.py

@@ -1275,6 +1275,7 @@ def in_time_placebo(
                 - ``pre_fit_rmse`` — RMSE on the fake pre-window
                 - ``n_pre_fake`` — periods before the fake date
                 - ``n_post_fake`` — periods from the fake date onward
+
             NaN is emitted only for dimensional infeasibility. Frank-Wolfe
             does not expose a mid-solver non-convergence signal; inspect
             ``pre_fit_rmse`` for poor refit quality.

diff_diff/triple_diff.py

@@ -355,11 +355,13 @@ class TripleDifference:
 
     Estimates the Average Treatment effect on the Treated (ATT) when treatment
     requires satisfying two criteria: belonging to a treated group AND being
-    in an eligible partition of the population.
+    in an eligible partition of the population. The DDD design was popularized
+    by Gruber (1994) [2]_.
 
-    This implementation follows Ortiz-Villavicencio & Sant'Anna (2025), which
-    shows that naive DDD implementations (difference of two DiDs, three-way
-    fixed effects) are invalid when covariates are needed for identification.
+    This implementation follows Ortiz-Villavicencio & Sant'Anna (2025) [1]_,
+    which shows that naive DDD implementations (difference of two DiDs,
+    three-way fixed effects) are invalid when covariates are needed for
+    identification.
 
     Parameters
     ----------

docs/_templates/autosummary/class.rst

@@ -0,0 +1,26 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+{% block methods %}
+{% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+{% for item in methods %}
+      ~{{ name }}.{{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
+{% block attributes %}
+{% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+{% for item in attributes %}
+      ~{{ name }}.{{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/_templates/autosummary/function.rst

@@ -0,0 +1,6 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+   :no-index:

docs/api/_autosummary/diff_diff.BaconDecomposition.rst

@@ -4,24 +4,20 @@
 .. currentmodule:: diff_diff
 
 .. autoclass:: BaconDecomposition
+   :no-members:
 
-   
-   .. automethod:: __init__
 
-   
    .. rubric:: Methods
 
    .. autosummary::
-   
+
       ~BaconDecomposition.__init__
       ~BaconDecomposition.fit
       ~BaconDecomposition.get_params
       ~BaconDecomposition.print_summary
       ~BaconDecomposition.set_params
       ~BaconDecomposition.summary
-   
-   
 
-   
-   
-   
+
+
+

docs/api/_autosummary/diff_diff.BaconDecompositionResults.rst

@@ -4,32 +4,30 @@
 .. currentmodule:: diff_diff
 
 .. autoclass:: BaconDecompositionResults
+   :no-members:
 
-   
-   .. automethod:: __init__
 
-   
    .. rubric:: Methods
 
    .. autosummary::
-   
+
       ~BaconDecompositionResults.__init__
       ~BaconDecompositionResults.effect_by_type
       ~BaconDecompositionResults.print_summary
       ~BaconDecompositionResults.summary
       ~BaconDecompositionResults.to_dataframe
       ~BaconDecompositionResults.weight_by_type
-   
-   
 
-   
-   
+
+
+
    .. rubric:: Attributes
 
    .. autosummary::
-   
+
       ~BaconDecompositionResults.decomposition_error
       ~BaconDecompositionResults.n_obs
+      ~BaconDecompositionResults.survey_metadata
       ~BaconDecompositionResults.twfe_estimate
       ~BaconDecompositionResults.comparisons
       ~BaconDecompositionResults.total_weight_treated_vs_never
@@ -41,5 +39,4 @@
       ~BaconDecompositionResults.n_timing_groups
       ~BaconDecompositionResults.n_never_treated
       ~BaconDecompositionResults.timing_groups
-   
-   
+

docs/api/_autosummary/diff_diff.CSBootstrapResults.rst

@@ -4,25 +4,22 @@
 .. currentmodule:: diff_diff
 
 .. autoclass:: CSBootstrapResults
+   :no-members:
 
-   
-   .. automethod:: __init__
 
-   
    .. rubric:: Methods
 
    .. autosummary::
-   
+
       ~CSBootstrapResults.__init__
-   
-   
 
-   
-   
+
+
+
    .. rubric:: Attributes
 
    .. autosummary::
-   
+
       ~CSBootstrapResults.bootstrap_distribution
       ~CSBootstrapResults.cband_crit_value
       ~CSBootstrapResults.event_study_cis
@@ -40,5 +37,4 @@
       ~CSBootstrapResults.group_time_ses
       ~CSBootstrapResults.group_time_cis
       ~CSBootstrapResults.group_time_p_values
-   
-   
+

docs/api/_autosummary/diff_diff.CallawaySantAnna.rst

@@ -4,35 +4,32 @@
 .. currentmodule:: diff_diff
 
 .. autoclass:: CallawaySantAnna
+   :no-members:
 
-   
-   .. automethod:: __init__
 
-   
    .. rubric:: Methods
 
    .. autosummary::
-   
+
       ~CallawaySantAnna.__init__
+      ~CallawaySantAnna.diagnose_propensity
       ~CallawaySantAnna.fit
       ~CallawaySantAnna.get_params
       ~CallawaySantAnna.print_summary
       ~CallawaySantAnna.set_params
       ~CallawaySantAnna.summary
-   
-   
 
-   
-   
+
+
+
    .. rubric:: Attributes
 
    .. autosummary::
-   
+
       ~CallawaySantAnna.n_bootstrap
       ~CallawaySantAnna.bootstrap_weights
       ~CallawaySantAnna.alpha
       ~CallawaySantAnna.seed
       ~CallawaySantAnna.anticipation
       ~CallawaySantAnna.base_period
-   
-   
+

docs/api/_autosummary/diff_diff.CallawaySantAnnaResults.rst

@@ -4,39 +4,51 @@
 .. currentmodule:: diff_diff
 
 .. autoclass:: CallawaySantAnnaResults
+   :no-members:
 
-   
-   .. automethod:: __init__
 
-   
    .. rubric:: Methods
 
    .. autosummary::
-   
+
       ~CallawaySantAnnaResults.__init__
+      ~CallawaySantAnnaResults.epv_summary
       ~CallawaySantAnnaResults.print_summary
       ~CallawaySantAnnaResults.summary
       ~CallawaySantAnnaResults.to_dataframe
-   
-   
 
-   
-   
+
+
+
    .. rubric:: Attributes
 
    .. autosummary::
-   
+
       ~CallawaySantAnnaResults.alpha
+      ~CallawaySantAnnaResults.anticipation
+      ~CallawaySantAnnaResults.att
       ~CallawaySantAnnaResults.base_period
       ~CallawaySantAnnaResults.bootstrap_results
       ~CallawaySantAnnaResults.cband_crit_value
+      ~CallawaySantAnnaResults.coef_var
+      ~CallawaySantAnnaResults.conf_int
       ~CallawaySantAnnaResults.control_group
+      ~CallawaySantAnnaResults.epv_diagnostics
+      ~CallawaySantAnnaResults.epv_threshold
       ~CallawaySantAnnaResults.event_study_effects
+      ~CallawaySantAnnaResults.event_study_vcov
+      ~CallawaySantAnnaResults.event_study_vcov_index
       ~CallawaySantAnnaResults.group_effects
       ~CallawaySantAnnaResults.influence_functions
       ~CallawaySantAnnaResults.is_significant
+      ~CallawaySantAnnaResults.p_value
+      ~CallawaySantAnnaResults.panel
+      ~CallawaySantAnnaResults.pscore_fallback
       ~CallawaySantAnnaResults.pscore_trim
+      ~CallawaySantAnnaResults.se
       ~CallawaySantAnnaResults.significance_stars
+      ~CallawaySantAnnaResults.survey_metadata
+      ~CallawaySantAnnaResults.t_stat
       ~CallawaySantAnnaResults.group_time_effects
       ~CallawaySantAnnaResults.overall_att
       ~CallawaySantAnnaResults.overall_se
@@ -48,5 +60,4 @@
       ~CallawaySantAnnaResults.n_obs
       ~CallawaySantAnnaResults.n_treated_units
       ~CallawaySantAnnaResults.n_control_units
-   
-   
+