Address PR #396 R1 review (1 P1 + 1 P2)

P1: troubleshooting:block17/block18 are not actually context-dependent
within docs/troubleshooting.rst — the page has no prior HAD est/results
binding before the new HAD Issues section. Suppressing NameError on
those IDs hid broken docs (the readers' copy-paste would fail) while
CI stopped reporting the failure.

Fix: rewrote both snippets self-contained, mirroring the inline HAD-
shape panel construction pattern from PR #396's r_comparison:block6
fix and the upstream choosing_estimator:block7 fix in 55d7a27.
- block17 (Resolved estimand inspection): inline 200-unit / 5-period
  HAD panel with beta(0.5, 1.0) doses — d.min() near zero so the
  Design 1' (continuous_at_zero) detection rule fires and `target_
  parameter == "WAS"` for the inspection demo.
- block18 (Mass-point design selected): inline 200-unit / 5-period
  HAD panel where 30% of units share d_lower=0.5 so the
  modal-fraction-at-d.min() > 2% threshold trips and `_detect_design`
  resolves to mass_point. Verified locally: design='mass_point',
  target_parameter='WAS_d_lower'.

Both snippets now define `est` and `results` locally; removed
troubleshooting:block17 and troubleshooting:block18 from
_CONTEXT_DEPENDENT_SNIPPETS.

P2: r_comparison:block6 was already in _CONTEXT_DEPENDENT_SNIPPETS
from a pre-existing entry, but PR #396's earlier rewrite already made
it self-contained. The stale allowlist entry would mask future
NameError regressions. Removed.

Verification: PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest
tests/test_doc_snippets.py reports 111 passed, 4 skipped, 0 failed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

docs/troubleshooting.rst

@@ -498,17 +498,36 @@ is meaningfully positive relative to the dose scale.
 
 .. code-block:: python
 
-   # Inspect the dose support before fitting
    import numpy as np
-   d = data['dose'].to_numpy()
-   print(data['dose'].describe())
+   import pandas as pd
+   from diff_diff import HeterogeneousAdoptionDiD
+
+   # Build a HAD-shape panel: D=0 in pre-periods (t < F), D > 0 only at F+.
+   rng = np.random.default_rng(42)
+   G, F, T = 200, 4, 5
+   doses = rng.beta(0.5, 1.0, size=G)
+   rows = []
+   for g in range(G):
+       for t in range(1, T + 1):
+           y = (rng.normal()
+                + (doses[g] + doses[g] ** 2) * (t >= F)
+                + rng.normal(0, 0.5))
+           d = doses[g] if t >= F else 0.0
+           rows.append({'unit': g, 'period': t, 'y': y, 'dose': d})
+   had_data = pd.DataFrame(rows)
+
+   # Inspect the dose support before fitting
+   d = had_data['dose'].to_numpy()
+   print(had_data['dose'].describe())
    print(f"d.min() = {d.min():.6g}; "
          f"0.01 * median(|d|) = {0.01 * np.median(np.abs(d)):.6g}; "
          f"d.min() < threshold => Design 1' (WAS)")
 
    # Check the resolved estimand after fitting
-   results = est.fit(data, outcome_col='y', unit_col='unit',
-                     time_col='period', dose_col='dose')
+   est = HeterogeneousAdoptionDiD()
+   results = est.fit(had_data, outcome_col='y', unit_col='unit',
+                     time_col='period', dose_col='dose',
+                     aggregate='event_study')
    print(f"Resolved: {results.target_parameter}")
 
    # If you intend Design 1' but `d.min()` exceeds the threshold, verify
@@ -536,6 +555,37 @@ SE path is not used here).
 
 .. code-block:: python
 
+   import numpy as np
+   import pandas as pd
+   from diff_diff import HeterogeneousAdoptionDiD
+
+   # Build a HAD panel with a heavy boundary mass at d_lower so the
+   # modal fraction at d.min() exceeds 2% and `_detect_design` resolves
+   # to `mass_point`.
+   rng = np.random.default_rng(42)
+   G, F, T = 200, 4, 5
+   d_lower = 0.5
+   mass_frac = 0.3
+   doses = np.where(
+       rng.uniform(size=G) < mass_frac,
+       d_lower,
+       rng.uniform(d_lower + 0.1, 2.0, size=G),
+   )
+   rows = []
+   for g in range(G):
+       for t in range(1, T + 1):
+           y = (rng.normal()
+                + doses[g] * (t >= F)
+                + rng.normal(0, 0.5))
+           d = doses[g] if t >= F else 0.0
+           rows.append({'unit': g, 'period': t, 'y': y, 'dose': d})
+   had_data = pd.DataFrame(rows)
+
+   est = HeterogeneousAdoptionDiD()
+   results = est.fit(had_data, outcome_col='y', unit_col='unit',
+                     time_col='period', dose_col='dose',
+                     aggregate='event_study')
+
    # Inspect the resolved design
    print(f"Design: {results.design}")  # 'mass_point' here
 

tests/test_doc_snippets.py

@@ -365,11 +365,8 @@ def _restore_datasets_module():
     "r_comparison:block2",
     "r_comparison:block3",
     "r_comparison:block4",
-    "r_comparison:block6",
     "r_comparison:block7",
     "troubleshooting:block8",
-    "troubleshooting:block17",
-    "troubleshooting:block18",
 }