Add documentation site (docs.givecalc.org) with Jupyter Book

[MaxGhenis]

Summary

Create a documentation site at docs.givecalc.org using Jupyter Book 2 (JB2) to document both the web application and the underlying Python package.

Motivation

The givecalc Python package could be useful to others beyond the web app:

• Researchers analyzing charitable giving tax incentives
• Financial planners building custom tools
• Policy analysts modeling donation behavior
• Developers integrating tax calculations into other applications

Proposed Structure

docs/
├── index.md                    # Landing page
├── user-guide/
│   ├── getting-started.md      # How to use givecalc.org
│   ├── income-types.md         # Supported income sources
│   ├── deductions.md           # Itemized deductions explained
│   ├── year-selection.md       # Multi-year calculations
│   └── interpreting-results.md # Understanding the charts
├── python-package/
│   ├── installation.md         # pip install givecalc
│   ├── quickstart.ipynb        # Jupyter notebook tutorial
│   ├── api-reference.md        # Function documentation
│   ├── examples/
│   │   ├── basic-calculation.ipynb
│   │   ├── donation-curves.ipynb
│   │   ├── state-comparison.ipynb
│   │   └── target-donation.ipynb
│   └── advanced/
│       ├── custom-situations.md
│       └── policyengine-integration.md
├── methodology/
│   ├── tax-calculations.md     # How taxes are computed
│   ├── marginal-rates.md       # Marginal savings rate explanation
│   └── limitations.md          # Known limitations and assumptions
├── api/
│   ├── endpoints.md            # REST API documentation
│   └── schemas.md              # Request/response formats
└── contributing.md             # How to contribute

Technical Details

• Use Jupyter Book 2 (JB2) from https://next.jupyterbook.org/
• Follow the same pattern as other PolicyEngine docs
• Build with jb build docs (JB2 syntax)
• Deploy to GitHub Pages at docs.givecalc.org
• Include executable Jupyter notebooks with real examples
• Auto-generate API reference from docstrings

Example Notebook Content

from givecalc import create_situation, calculate_donation_effects

# Create a situation for a California single filer
situation = create_situation(
    wages_and_salaries=100000,
    state_code="CA",
    is_married=False,
    year=2025
)

# Calculate tax impact across donation range
df = calculate_donation_effects(situation)

# Plot marginal savings rate
df.plot(x='charitable_cash_donations', y='marginal_savings')

Tasks

• Set up JB2 structure in docs/ directory
• Write user guide for web application
• Create Python package quickstart notebook
• Document all public functions with docstrings
• Add example notebooks with real calculations
• Configure GitHub Actions for docs deployment
• Set up docs.givecalc.org subdomain

References

• JB2 documentation: https://next.jupyterbook.org/
• PolicyEngine-US docs (example): https://policyengine.github.io/policyengine-us/