docs: fix 86 Sphinx ERRORs (PR 1 of 2-PR cleanup)

[igerber]

Summary

PR 1 of a 2-PR Sphinx cleanup sequence. Drops make html ERROR count
from 86 to 0, unblocking eventual -W enforcement in docs-tests.yml.
WARNING count drops collaterally from 2,199 to 2,170. The systemic
~2,000 duplicate object description class is deferred to PR 2.

Class A - Undefined substitution references (~50 instances). RST
treats |X| as a substitution-reference; on |ATT|, |overall ATT|,
|DID_M|, |h|, |Omega_0|, |delta_{...}|, etc. with no defined
substitution, the build errors. Per-context fix:

• coef_var docstrings across results.py and 11 *_results.py
  files: SE / |ATT| -> SE / abs(ATT) (plain English, readable in
  help()).
• imputation.py / two_stage.py horizon parameter: |h| -> abs(h).
• imputation_results.py matrix-cardinality: |Omega_1| ->
  :math:`|\Omega_1|` .
• honest_did.py Delta-class smoothness/relative-magnitude
  restrictions: inline |delta_{t+1} - delta_t| math -> .. math::
  block (DeltaSD, DeltaRM) or inline :math: (DeltaSDRM list
  items), with \delta LaTeX rendering.
• trop.py / trop_results.py / docs/api/trop.rst: |s-t| and
  |t-s| -> :math:`|s-t|` .

Class B - Unexpected indentation in numpydoc bullet lists. RST
requires a blank line between a colon-terminated description line and
the bullet list that follows. Affected sites use the same pattern:
parameter X : type description ending with :, then bullets without
blank line. Fix is a single inserted blank line per site, applied to
docstrings in: bacon_decompose, staggered.CallawaySantAnna,
triple_diff.TripleDifference, twfe.TwoWayFixedEffects.decompose,
synthetic_did.SyntheticDiD, prep.rank_control_units,
had.HeterogeneousAdoptionDiDResults, and
results.SyntheticDiDResults.get_loo_effects_df.

Other fixes:

• diagnostic_report.py:DiagnosticReport: collapsed multi-line
  parameter name list (run_parallel_trends, run_sensitivity, ...)
  to single line so RST recognizes the parameter group; replaced
  em-dash with hyphen per repo convention.
• docs/api/local_linear.rst:48: replaced .. autodata:: KERNELS
  (which Sphinx tries to construct a docstring for via autodoc,
  hitting RST parse errors on the surrounding source comments) with
  manual .. py:data:: directive carrying the same content.

Methodology references

N/A - all changes are RST formatting in docstrings or RST source. No
estimator logic, defaults, weighting, or inference behavior changed.

Validation

• make html: 0 ERRORs (was 86), 2,170 WARNINGs (was 2,199).
• pytest tests/test_doc_snippets.py: 111 passed, 4 skipped (unchanged
  Batch C baseline; new RST in local_linear.rst has no code-blocks).
• git diff origin/main...HEAD | grep '^+' | grep -c '—' returns 0.
• 25 files changed: 23 source *.py (docstring formatting only) +
  docs/api/local_linear.rst + docs/api/trop.rst. No test changes
  needed (no behavior change).

Out of scope (queued)

Follow-up	Plan
PR 2: Fix systemic duplicate object description warnings	~2,000+ warnings from page-level autoclass :members: overlapping with checked-in autosummary stubs. Most likely add :no-index: to ~25-30 page-level directives in docs/api/*.rst per Sphinx's recommended fix. Architectural decision worth its own plan + review.
PR 3: Add -W to docs-tests.yml build	After PR 2, modify the workflow's Build docs step with SPHINXOPTS="-W". Locks in the cleanup permanently.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall Assessment

✅ Looks good — No unmitigated P0/P1 findings found.

Executive Summary

• The PR changes only docstrings/RST presentation in the provided diff; no estimator logic, defaults, weighting, variance, SE, or inference behavior changed.
• Methodology-adjacent formula edits for HonestDiD and TROP match docs/methodology/REGISTRY.md.
• Pattern-wide inference audit found no new inline t_stat = ... / se or partial NaN-guard defects in the changed surfaces.
• Sibling-surface audit found the main mirrored documentation surfaces updated consistently, especially TROP class docs and API docs.
• I did not independently run make html or pytest because the sandbox is read-only; review is based on the provided diff plus read-only audits.

Methodology

Finding: No methodology defects.

• Severity: P3 informational
• Impact: The edited HonestDiD formulas in diff_diff/honest_did.py:L38-L120 match the registry’s Delta^SD and Delta^RM definitions in docs/methodology/REGISTRY.md:L2635-L2671. The TROP absolute-distance wording in diff_diff/trop.py:L43-L57 and docs/api/trop.rst:L1-L16 is mathematically equivalent and matches the registry’s TROP weighting context in docs/methodology/REGISTRY.md:L1986-L2018.
• Concrete fix: None required.

Code Quality

Finding: No code-quality blockers.

• Severity: P3 informational
• Impact: The edits are documentation-only. The long parameter-name line in diff_diff/diagnostic_report.py:L259-L264 is a deliberate RST/numpydoc parsing fix, not behavior-bearing code.
• Concrete fix: None required.

Performance

Finding: No performance impact.

• Severity: P3 informational
• Impact: No runtime paths, estimator loops, matrix operations, bootstrap code, or variance code changed.
• Concrete fix: None required.

Maintainability

Finding: Sibling documentation surfaces appear mirrored.

• Severity: P3 informational
• Impact: The main repeated coef_var docstring pattern was updated consistently across result classes, e.g. diff_diff/results.py:L143-L149, diff_diff/results.py:L470-L476, and diff_diff/results.py:L921-L927. TROP’s API and class-level descriptions were both updated.
• Concrete fix: None required.

Tech Debt

Finding: Remaining duplicate-object Sphinx warnings are tracked.

• Severity: P3 informational
• Impact: The deferred duplicate-object warning class is already listed under TODO.md:L134, so it is not a blocker under the review instructions.
• Concrete fix: None required for this PR.

Security

Finding: No security issues found.

• Severity: P3 informational
• Impact: The diff contains docstring/RST formatting only; no secrets, credential handling, subprocess behavior, network behavior, or file I/O paths changed.
• Concrete fix: None required.

Documentation/Tests

Finding: Documentation cleanup is consistent with the PR scope.

• Severity: P3 informational
• Impact: The local_linear change replaces autodata with a manual py:data directive at docs/api/local_linear.rst:L48-L51, avoiding autodoc parsing of the problematic source context while preserving the documented public symbol. No workflow paths: or pytest-selection changes are present in the diff, so the transitive workflow dependency audit is not applicable.
• Concrete fix: None required.