docs: utility coverage gaps (RTD audit Batch C) by igerber · Pull Request #403 · igerber/diff-diff · GitHub
Skip to content

docs: utility coverage gaps (RTD audit Batch C)#403

Merged
igerber merged 2 commits into
mainfrom
docs-rtd-audit-batch-c-pr
May 9, 2026
Merged

docs: utility coverage gaps (RTD audit Batch C)#403
igerber merged 2 commits into
mainfrom
docs-rtd-audit-batch-c-pr

Conversation

@igerber

@igerber igerber commented May 9, 2026

Copy link
Copy Markdown
Owner

Summary

RTD audit Batch C closes three utility-coverage gaps surfaced during the
docs refresh initiative:

  • New docs/api/profile.rst - covers profile_panel plus the four
    supporting dataclasses (PanelProfile, OutcomeShape,
    TreatmentDoseShape, Alert). All five are public top-level exports
    but had no API reference. Lands under a new "Pre-Fit Profiling" toctree
    section in docs/api/index.rst.
  • New docs/api/local_linear.rst - covers all 11 top-level
    local-linear infrastructure symbols (kernels, kernel-moment constants,
    local_linear_fit, mse_optimal_bandwidth,
    bias_corrected_local_linear, and result dataclasses). Lands under a
    new "Infrastructure" toctree section. Deliberately not placed under
    "Estimators" - the symbols are building blocks HeterogeneousAdoptionDiD
    composes, not estimators themselves.
  • docs/conf.py - html_extra_path now includes
    llms-autonomous.txt (65KB). The file ships in the wheel but was not
    previously exposed via Sphinx, so the practitioner-profile prose link
    to it from profile.rst:11 now resolves on RTD.

docs/doc-deps.yaml: extends the existing local_linear.py entry to
point at the new api/local_linear.rst; adds a new top-level
diff_diff/profile.py entry at drift_risk: low (descriptive-only by
design, sits with prep.py / datasets.py not the linalg.py /
utils.py methodology-stake tier).

Drive-by: 1-line RST formatting fix in BaconDecomposition Parameters
docstring (blank line before bullet list) noticed during the deferred
Sphinx -W investigation.

Methodology references (required if estimator / math changes)

  • N/A - no methodology changes. Only diff_diff/bacon.py is touched in
    source, and only the RST formatting of an existing docstring (no logic,
    no signature, no semantics).

Validation

  • Tests added/updated: none required (docs-only PR; no behavior change).
    The new RST files contain no .. code-block:: python directives, so
    tests/test_doc_snippets.py reports zero new cases.
  • tests/test_doc_snippets.py baseline (locally, pure-Python backend):
    111 passed, 4 skipped (unchanged from origin/main; new files
    introduce no snippets).
  • Sphinx HTML build (no -W): zero warnings on profile.rst,
    local_linear.rst, index.rst
    , zero new autosummary stub
    warnings. Pre-existing backlog of 2,200+ warnings on other files stays
    out of scope (deferred to a separate -W cleanup PR).
  • Rendered-HTML spot checks: all 5 profile symbols and all 11
    local-linear symbols render in their respective pages;
    docs/_build/html/llms-autonomous.txt is served from html_extra_path;
    profile.html contains exactly one href="../llms-autonomous.txt"
    matching the prose link.

Security / privacy

  • Confirm no secrets/PII in this PR: Yes

Generated with Claude Code

…llms-autonomous.txt

Closes three RTD coverage gaps surfaced during the docs audit:

1. profile_panel and its 4 supporting dataclasses (PanelProfile,
   OutcomeShape, TreatmentDoseShape, Alert) are public top-level exports
   but had no API reference. New docs/api/profile.rst covers all 5 symbols
   under a new "Pre-Fit Profiling" toctree section.

2. The 11 top-level local-linear infrastructure symbols (kernels,
   kernel_moments, local_linear_fit, mse_optimal_bandwidth,
   bias_corrected_local_linear, and their result dataclasses) had no API
   reference. New docs/api/local_linear.rst covers all 11 under a new
   "Infrastructure" toctree section (sibling to Estimators, not a peer of
   HAD/EfficientDiD - the symbols are building blocks HAD composes).

3. llms-autonomous.txt (65KB) shipped in the wheel but was not exposed via
   Sphinx. Added to docs/conf.py html_extra_path; the practitioner-profile
   prose link in profile.rst now resolves on RTD.

doc-deps.yaml: extends existing local_linear.py entry to point at the new
api/local_linear.rst; adds new diff_diff/profile.py top-level entry at
drift_risk: low (descriptive-only by design, sits with prep.py / datasets.py
not the linalg.py / utils.py methodology-stake tier).

Drive-by: 1-line RST formatting fix in BaconDecomposition Parameters
docstring (blank line before bullet list) noticed during the deferred
Sphinx -W investigation.

Verification: sphinx make html shows zero warnings on the three new/edited
files (pre-existing -W backlog out of scope). Rendered HTML confirms all 16
new symbols render and llms-autonomous.txt is served from html_extra_path.
test_doc_snippets.py: 111 passed, 4 skipped (unchanged baseline; new RST
files contain no code-blocks).

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

github-actions Bot commented May 9, 2026

Copy link
Copy Markdown

Tighten the local_linear.rst overview to distinguish the generic helpers
from the HAD-scoped public wrappers, surfacing the Phase 1b/1c contract
that lives in REGISTRY.md and the source docstrings:

- Generic helpers (local_linear_fit, kernels, kernel_moments, KERNELS)
  remain usable on their own for any one-sided boundary local-linear
  regression problem with a strictly nonnegative running variable.
- HAD-scoped wrappers (mse_optimal_bandwidth,
  bias_corrected_local_linear) are explicitly hard-coded to the HAD
  Phase 1b/1c configuration and only those settings are parity-tested
  against R nprobust. Callers needing the broader surface drop to
  diff_diff._nprobust_port and accept that parity is not verified.

Cross-references diff_diff/local_linear.py:695-705 (Phase 1b),
:972-980 (Phase 1c), and REGISTRY.md HeterogeneousAdoptionDiD section
for the full contract.

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

igerber commented May 9, 2026

Copy link
Copy Markdown
Owner Author

/ai-review

@github-actions

github-actions Bot commented May 9, 2026

Copy link
Copy Markdown

@igerber igerber added the ready-for-ci Triggers CI test workflows label May 9, 2026
@igerber igerber merged commit fe80295 into main May 9, 2026
28 of 29 checks passed
@igerber igerber deleted the docs-rtd-audit-batch-c-pr branch May 9, 2026 16:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-ci Triggers CI test workflows

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant