Document time-specific input format #6355
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add clear documentation for time-specific input format in README - Create Getting Started guide in documentation - Include warning about incorrect calculations when using wrong format - Add examples showing the difference between simple and time-specific formats Fixes PolicyEngine#6354 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
Major documentation overhaul including: 1. Policy Reference Documentation - Separated policy logic from code examples - Created detailed program documentation for IRS, USDA, SSA, HHS programs - Added legislative references and historical context - Structured for potential journal publication 2. Institutional User Documentation - Congressional analysis workflows (JEC methodology) - Microsimulation methodology and validation - Use cases for different user types 3. API Documentation - Complete Python API reference - Common patterns and examples - Performance optimization tips 4. Program Summary Tables - Comprehensive overview of all modeled programs - Federal, state, and local programs - Key parameters and eligibility criteria 5. Automated Documentation Generation - Script to generate parameter documentation from YAML files - Extracts metadata, references, and historical values This restructure provides institutional-grade documentation suitable for users from JEC, Barclays, NBER, U Michigan and other research institutions. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
The notebook-issue-creator agent has been moved to ~/.claude/agents/ for global availability across all projects.
- Create generate_variable_docs.py to extract metadata from all variables - Update generate_parameter_docs.py (already existed) - Integrate both into make documentation workflow - Add Variables and Parameters reference sections to _toc.yml - Document the auto-generation process in contributing guide This provides comprehensive, searchable documentation for all ~5000+ variables and parameters in PolicyEngine US, automatically kept in sync with the code.
- Run make format on documentation generator scripts - Replace mermaid diagram with numbered list in workflow.md - Fix tab-set syntax in documentation.md - Ensure all Python code passes Black formatting
- Document Python 3.13 as the default and recommended version - Add comprehensive guide for building and viewing docs locally - Update .gitignore to exclude all .venv-* directories - Include troubleshooting for common documentation build issues
- Add detailed Child Tax Credit documentation with full legislative history - Add comprehensive Unemployment Insurance documentation covering federal-state structure - Include eligibility criteria, benefit calculations, and program interactions - Follow Atlanta Fed Policy Rules Database style with tables and examples - Add step-by-step calculations and state variation details
- Create generate_latex_paper.py to convert markdown docs to LaTeX - Generate academic journal-quality paper from policy documentation - Include all major programs (EITC, CTC, SNAP, UI) with full details - Add LaTeX generation to make documentation workflow - Use basic LaTeX packages for wider compatibility
- Create docs/README.md with complete instructions - Include all viewing options (local build, GitHub Pages) - Document the full structure and features - Add quick links to key documentation sections
|
This PR is adding the entire documentation suite right, if so, can we rename and structure some of the contents similarly to the UK version here? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds documentation for the time-specific input format that's required when calculating benefits for specific years.
Problem
As discovered in #6354, users were getting incorrect calculations when using the simple format for year-specific calculations instead of the required dictionary format.
Changes
Updated README.md:
Created Getting Started guide (docs/usage/getting_started.md):
Updated documentation TOC to include the new Getting Started guide
Impact
This documentation will help users avoid the confusion that led to incorrect SNAP calculations (e.g., getting $206/month instead of the correct $249/month for 2025).
Fixes #6354