Skip to content

Commit 577d32f

Browse files
claudeclaude
committed
Add API documentation site with Sphinx
Build complete API documentation site for diff-diff library: - Sphinx configuration with autodoc, napoleon, and intersphinx - ReadTheDocs configuration for automated builds - Full API reference auto-generated from docstrings - User guide pages: - Getting started / quickstart - "Which estimator should I use?" decision guide - Comparison with R packages (did, HonestDiD, synthdid) - Module documentation for all public APIs: - Estimators (DifferenceInDifferences, TWFE, MultiPeriodDiD, SyntheticDiD) - Staggered (CallawaySantAnna) - Results classes - Visualization functions - Diagnostics / placebo tests - Honest DiD sensitivity analysis - Utils (parallel trends, wild bootstrap) - Data preparation utilities Build locally with: cd docs && make html Completes the API Documentation Site item from TODO.md (1.0 blocker).
1 parent 8c5ed73 commit 577d32f

66 files changed

Lines changed: 3075 additions & 15 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,9 @@ ENV/
4646
# Jupyter
4747
.ipynb_checkpoints/
4848

49+
# Sphinx documentation
50+
docs/_build/
51+
4952
# OS
5053
.DS_Store
5154
Thumbs.db

‎.readthedocs.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Read the Docs configuration file
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3+
4+
version: 2
5+
6+
# Set the OS, Python version, and other tools you might need
7+
build:
8+
os: ubuntu-22.04
9+
tools:
10+
python: "3.11"
11+
12+
# Build documentation in the "docs/" directory with Sphinx
13+
sphinx:
14+
configuration: docs/conf.py
15+
16+
# Optionally, but recommended: declare the Python requirements
17+
# required to build your documentation
18+
python:
19+
install:
20+
- method: pip
21+
path: .
22+
extra_requirements:
23+
- docs

‎TODO.md‎

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ A production-ready DiD library needs:
1010
3. ✅ **Assumption diagnostics** - Parallel trends tests, placebo tests
1111
4. ⚠️ **Sensitivity analysis** - What if parallel trends is violated? (Rambachan-Roth)
1212
5. ⚠️ **Conditional parallel trends** - Covariate adjustment for staggered DiD
13-
6. ⚠️ **Documentation** - API reference site for discoverability
13+
6. ✅ **Documentation** - API reference site for discoverability
1414

1515
---
1616

@@ -20,7 +20,7 @@ A production-ready DiD library needs:
2020
|---------|--------|----------|----------------|
2121
| **Honest DiD (Rambachan-Roth)** | ✅ Implemented | 1.0 Blocker | Reviewers expect sensitivity analysis |
2222
| **CallawaySantAnna Covariates** | ✅ Implemented | 1.0 Blocker | Conditional PT often required in practice |
23-
| **API Documentation Site** | Not Started | 1.0 Blocker | Credibility and discoverability |
23+
| **API Documentation Site** | ✅ Implemented | 1.0 Blocker | Credibility and discoverability |
2424
| Goodman-Bacon Decomposition | Not Started | 1.0 Target | Explains when TWFE fails |
2525
| Power Analysis | Not Started | 1.0 Target | Study design tool |
2626
| CallawaySantAnna Bootstrap | Not Implemented | 1.0 Target | Better inference with few clusters |
@@ -92,21 +92,30 @@ results = cs.fit(
9292
```
9393

9494
### API Documentation Site
95-
**Status**: Not Started
95+
**Status**: ✅ Implemented
9696
**Effort**: Medium
9797
**Practitioner Value**: ⭐⭐⭐⭐
9898

99-
**Why this matters**: For a 1.0 release, users should be able to find comprehensive API documentation online. Currently only docstrings and README exist.
99+
**Why this matters**: For a 1.0 release, users should be able to find comprehensive API documentation online.
100100

101-
**Options**:
102-
- Sphinx + ReadTheDocs (traditional, well-supported)
103-
- mkdocs-material (modern, clean look)
104-
- pdoc (simple, auto-generates from docstrings)
105-
106-
**Should include**:
107-
- Full API reference
108-
- "When to use which estimator" decision guide
109-
- Comparison with R packages (`did`, `HonestDiD`, `synthdid`)
101+
**Implementation**:
102+
- ✅ Sphinx + ReadTheDocs theme with autodoc and napoleon extensions
103+
- ✅ Full API reference auto-generated from docstrings
104+
- ✅ "Which estimator should I use?" decision guide with flowchart
105+
- ✅ Comparison with R packages (`did`, `HonestDiD`, `synthdid`)
106+
- ✅ Getting started / quickstart guide
107+
- ✅ ReadTheDocs configuration for automated builds
108+
- ✅ Module-by-module API documentation:
109+
- Estimators (DifferenceInDifferences, TWFE, MultiPeriodDiD, SyntheticDiD)
110+
- Staggered (CallawaySantAnna, CallawaySantAnnaResults, GroupTimeEffect)
111+
- Results (DiDResults, MultiPeriodDiDResults, SyntheticDiDResults, PeriodEffect)
112+
- Visualization (plot_event_study, plot_group_effects, plot_sensitivity, plot_honest_event_study)
113+
- Diagnostics (placebo tests, permutation tests, leave-one-out)
114+
- Honest DiD (HonestDiD, DeltaSD, DeltaRM, DeltaSDRM)
115+
- Utils (parallel trends testing, wild bootstrap)
116+
- Data Prep (generate_did_data, balance_panel, etc.)
117+
118+
**Build locally**: `cd docs && make html`
110119

111120
---
112121

@@ -295,7 +304,7 @@ Beyond the API site:
295304

296305
1. ✅ **CallawaySantAnna Covariates** - Makes the staggered estimator production-ready
297306
2. ✅ **Honest DiD (Rambachan-Roth)** - Addresses the key credibility gap
298-
3. **API Documentation Site** - Professional presentation
307+
3. ✅ **API Documentation Site** - Professional presentation
299308
4. **Goodman-Bacon Decomposition** - Key diagnostic for TWFE users
300309
5. **Power Analysis** - Study design tool practitioners need
301310

‎docs/Makefile‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Minimal makefile for Sphinx documentation
2+
3+
# You can set these variables from the command line, and also
4+
# from the environment for the first two.
5+
SPHINXOPTS ?=
6+
SPHINXBUILD ?= sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
20+
21+
# Custom targets
22+
livehtml:
23+
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
24+
25+
clean:
26+
rm -rf $(BUILDDIR)/*

‎docs/_static/custom.css‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
/* Custom CSS for diff-diff documentation */
2+
3+
/* Improve code block readability */
4+
.highlight {
5+
background: #f8f8f8 !important;
6+
}
7+
8+
/* Better table styling */
9+
table.docutils {
10+
width: 100%;
11+
border-collapse: collapse;
12+
}
13+
14+
table.docutils td, table.docutils th {
15+
padding: 8px 12px;
16+
border: 1px solid #e1e4e5;
17+
}
18+
19+
/* Improve admonition styling */
20+
.admonition {
21+
margin: 1em 0;
22+
padding: 12px;
23+
}
24+
25+
.admonition-title {
26+
font-weight: bold;
27+
}
28+
29+
/* Method/function signature styling */
30+
.sig-name {
31+
font-weight: bold;
32+
}
33+
34+
/* Better parameter list styling */
35+
.field-list {
36+
margin-top: 1em;
37+
}

‎docs/api/_autosummary/diff_diff.CallawaySantAnna.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
diff\_diff.CallawaySantAnna
2+
===========================
3+
4+
.. currentmodule:: diff_diff
5+
6+
.. autoclass:: CallawaySantAnna
7+
8+
9+
.. automethod:: __init__
10+
11+
12+
.. rubric:: Methods
13+
14+
.. autosummary::
15+
16+
~CallawaySantAnna.__init__
17+
~CallawaySantAnna.fit
18+
~CallawaySantAnna.get_params
19+
~CallawaySantAnna.print_summary
20+
~CallawaySantAnna.set_params
21+
~CallawaySantAnna.summary
22+
23+
24+
25+
26+
27+

‎docs/api/_autosummary/diff_diff.CallawaySantAnnaResults.rst‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
diff\_diff.CallawaySantAnnaResults
2+
==================================
3+
4+
.. currentmodule:: diff_diff
5+
6+
.. autoclass:: CallawaySantAnnaResults
7+
8+
9+
.. automethod:: __init__
10+
11+
12+
.. rubric:: Methods
13+
14+
.. autosummary::
15+
16+
~CallawaySantAnnaResults.__init__
17+
~CallawaySantAnnaResults.print_summary
18+
~CallawaySantAnnaResults.summary
19+
~CallawaySantAnnaResults.to_dataframe
20+
21+
22+
23+
24+
25+
.. rubric:: Attributes
26+
27+
.. autosummary::
28+
29+
~CallawaySantAnnaResults.alpha
30+
~CallawaySantAnnaResults.control_group
31+
~CallawaySantAnnaResults.event_study_effects
32+
~CallawaySantAnnaResults.group_effects
33+
~CallawaySantAnnaResults.influence_functions
34+
~CallawaySantAnnaResults.is_significant
35+
~CallawaySantAnnaResults.significance_stars
36+
~CallawaySantAnnaResults.group_time_effects
37+
~CallawaySantAnnaResults.overall_att
38+
~CallawaySantAnnaResults.overall_se
39+
~CallawaySantAnnaResults.overall_t_stat
40+
~CallawaySantAnnaResults.overall_p_value
41+
~CallawaySantAnnaResults.overall_conf_int
42+
~CallawaySantAnnaResults.groups
43+
~CallawaySantAnnaResults.time_periods
44+
~CallawaySantAnnaResults.n_obs
45+
~CallawaySantAnnaResults.n_treated_units
46+
~CallawaySantAnnaResults.n_control_units
47+
48+

‎docs/api/_autosummary/diff_diff.DeltaRM.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
diff\_diff.DeltaRM
2+
==================
3+
4+
.. currentmodule:: diff_diff
5+
6+
.. autoclass:: DeltaRM
7+
8+
9+
.. automethod:: __init__
10+
11+
12+
.. rubric:: Methods
13+
14+
.. autosummary::
15+
16+
~DeltaRM.__init__
17+
18+
19+
20+
21+
22+
.. rubric:: Attributes
23+
24+
.. autosummary::
25+
26+
~DeltaRM.Mbar
27+
28+

‎docs/api/_autosummary/diff_diff.DeltaSD.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
diff\_diff.DeltaSD
2+
==================
3+
4+
.. currentmodule:: diff_diff
5+
6+
.. autoclass:: DeltaSD
7+
8+
9+
.. automethod:: __init__
10+
11+
12+
.. rubric:: Methods
13+
14+
.. autosummary::
15+
16+
~DeltaSD.__init__
17+
18+
19+
20+
21+
22+
.. rubric:: Attributes
23+
24+
.. autosummary::
25+
26+
~DeltaSD.M
27+
28+

‎docs/api/_autosummary/diff_diff.DeltaSDRM.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
diff\_diff.DeltaSDRM
2+
====================
3+
4+
.. currentmodule:: diff_diff
5+
6+
.. autoclass:: DeltaSDRM
7+
8+
9+
.. automethod:: __init__
10+
11+
12+
.. rubric:: Methods
13+
14+
.. autosummary::
15+
16+
~DeltaSDRM.__init__
17+
18+
19+
20+
21+
22+
.. rubric:: Attributes
23+
24+
.. autosummary::
25+
26+
~DeltaSDRM.M
27+
~DeltaSDRM.Mbar
28+
29+

0 commit comments

Comments
 (0)