Add partner integration docs (MkDocs Material site)#1492
Closed
hua7450 wants to merge 5 commits into
Closed
Conversation
Adds the docs site framework with PolicyEngine brand styling (teal
primary, Inter + JetBrains Mono) and the first cookbook recipe
("When does my client lose SNAP this year?") as the tone reference.
Other pages are stubbed pending review of the recipe page.
GitHub Actions workflow deploys to GitHub Pages on push to main when
docs/ or mkdocs.yml change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces illustrative SNAP values in the cliff recipe with figures computed from policyengine-us 1.634.8 — CA family of 4 earning \$1,500/mo qualifies for \$276.10 SNAP, the cliff fires at \$2,000/mo. Removes navigation.tabs from the Material theme features so the entire navigation lives in the left sidebar (matches Claude API docs). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fills in the previously-stubbed pages: - Overview: working SNAP example with 200 response, hosted/self-hosted endpoints - Request format: entity table, members, inputs vs outputs, complete request returning real EITC/CTC/SNAP figures - Period keys: year vs month rules, mixed-shape budget split with worked $1,581.82/mo example, 400 catalog (malformed key, inconsistent full year), warnings array - Response format: 200/400/500/404 catalog, warnings field semantics - Cookbook hello-world: annual SNAP recipe matching the cliff recipe template - Changelog: PR #1490 entries, version-pinning instructions, format legend Numbers come from policyengine-us 1.634.8: CA family of 4 with \$30k earnings receives \$3,924.54 SNAP, \$7,316 EITC, \$4,400 CTC. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Use PolicyEngine white wordmark logo + favicon from policyengine-app-v2 - Drop "PolicyEngine" prefix from site_name (logo already says it) → header reads "POLICY ENGINE | Household API" - Hide right-side TOC pane (Claude-docs style — left nav only) - Hide per-page anchor links and redundant section labels in primary nav - Hide expand/collapse caret next to nested sections (always-expanded) - Increase header height (4rem) and title size (1.4rem) - Tighten sidebar item spacing for compact-but-readable layout Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…lors - Drop centered 61rem grid → header and main content span full viewport width (logo at left edge, sidebar against the wall) - Remove GitHub repo badge from header - Reorder header right side: [theme toggle] [search] (was [search] [theme toggle]) - Force "Household API" topic visible in header title (was hidden by Material's auto site-name/page-title swap) - Vertically center all header items - Force all heading levels (h1–h6) to use --md-default-fg-color (black) instead of Material's default muted gray for h1 - Zero double padding on the Cookbook section container so it aligns with peer items in the sidebar Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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
Adds a partner-facing documentation site at
docs/, built with MkDocs Material, deployed to GitHub Pages on push to main. Six pages covering the request shape, period keys, response format, two cookbook recipes, and a changelog. Designed to look like the Claude API docs — left sidebar nav, code samples with copy buttons, search — branded with PolicyEngine teal and the wordmark logo.Depends on PR #1490 merging first — the docs describe behavior from that fix (year-keyed inputs on month-defined variables, the
warningsarray, the new 400 catalog). Merging this docs PR before #1490 would publish docs for behavior that isn't on production yet.Pages
nullto compute), entity tablewarningsarrayNumbers in examples
All SNAP / EITC / CTC figures are computed against
policyengine-us 1.634.8for a CA family of 4:Deployment
.github/workflows/docs.ymlbuilds and deploys on every push to main whendocs/,mkdocs.yml, or the workflow itself changes. Once PR #1490 ships and this PR merges, the site goes live at:https://policyengine.github.io/policyengine-household-api/
To enable: Settings → Pages → Source: "GitHub Actions".
Branding
policyengine-app-v2docs/stylesheets/extra.cssmap Material's tokens to PolicyEngine's design system (teal#319795, Inter, JetBrains Mono, sentence-case)Test plan
mkdocs build --strictpasses locallyOut of scope (future PRs)
docs.policyengine.org/household-apior similar)