Complete documentation overhaul

[chekos]

Summary

• Rewrites the entire documentation site (25 new/rewritten pages) to cover all current library features: get_acs, get_pums, get_decennial, get_estimates, get_flows, MOE utilities, spatial support, survey design, caching, and CLI
• Upgrades from readthedocs theme to mkdocs-material with navigation tabs, code copy, admonitions, and tabbed content
• Adds 12 topic guides, 3 migration guides (tidycensus, old PyPUMS, FTP), Getting Started section with Census 101, and full API/CLI/datasets reference
• Removes outdated user-guide/, history.md, and surveys.md that documented only the deprecated ACS() class

What's new

Section	Pages
Getting Started	installation, quickstart (3 examples), census-101 (decision tree)
Guides	ACS, Decennial, PUMS, Estimates, Flows, Variables, Geography, MOE, Spatial, Survey Design, Caching, Multi-year
Reference	API (mkdocstrings), CLI, Datasets, Changelog
Migration	from-tidycensus, from-old-pypums, from-census-ftp
About	Contributing (updated), Authors (updated)

Test plan

• uv run mkdocs build completes with no errors
• Review rendered site with uv run mkdocs serve
• Spot-check code examples against Census API
• Verify all internal cross-links resolve correctly

🤖 Generated with Claude Code

[claude]

Claude finished @chekos's task in 2m 14s —— View job

---

PR Review: Complete Documentation Overhaul

• Read CLAUDE.md and gather repo context
• Review mkdocs.yml configuration
• Review documentation content and code examples
• Review non-documentation changes (README, CONTRIBUTING, pyproject.toml)
• Check for broken links, inconsistencies, and best practices
• Post final review

---

Summary

This is a substantial, well-structured documentation overhaul. The 25 new/rewritten pages are clearly written, well-organized with progressive disclosure (Level 1/2/3 for MOE, for example), and the migration to mkdocs-material brings a significant UX improvement. A few technical issues need addressing before merge.

---

Issues Found

🔴 Critical

1. Missing content.code.annotate feature flag in mkdocs.yml

docs/getting-started/quickstart.md uses code annotations extensively (# (1)! style with numbered callouts below each block), but mkdocs.yml is missing the required feature flag. Without it, the annotations render as raw inline comments instead of the interactive overlay.

# mkdocs.yml — add this to theme.features:
- content.code.annotate

The quickstart.md file uses this pattern in all three examples. Fix this →

---

🟡 Moderate

2. autorefs plugin not listed in pyproject.toml docs dependencies

mkdocs.yml uses the autorefs plugin (line 67), which enables cross-references like [CensusCache][pypums.cache.CensusCache] across the docs. It arrives transitively through mkdocstrings[python], but it's best practice to list it explicitly so the dependency is clear and won't break if mkdocstrings changes its transitive deps.

# pyproject.toml [project.optional-dependencies] docs
"mkdocs-autorefs",  # add this

3. pyproject.toml description still describes the old FTP-download library

Line 8 reads: "Download Public Use Micro Sample (PUMS) data files from the US Census Bureau's FTP server." This no longer matches the library's capabilities and will appear on PyPI. It should be updated to match the new scope, e.g. "Python interface to the US Census Bureau API for ACS, Decennial Census, PUMS, estimates, and migration flows."

Fix this →

---

🟢 Minor / Polish

4. Year inconsistency across examples

The default year in function signatures is 2023, and quickstart examples use 2023, but docs/index.md and README.md both use year=2022 in the quick-start snippets. This is not a bug, but aligning all "hello world" examples to the same year (prefer 2023 since it's the stated default) would reduce confusion for newcomers.

Affected locations:

• docs/index.md:17 — year=2022
• README.md:23 — year=2022
• README.md:31 — year=2022
• README.md:45 — year=2022

5. County parameter note in from-tidycensus.md needs a usage example

The parameter table at migration/from-tidycensus.md:27 correctly notes that PyPUMS requires FIPS codes for county while tidycensus accepts names, but doesn't show how to look them up. Right below it a quick one-liner would help:

# Look up the FIPS code first
from pypums.datasets import lookup_fips
fips = lookup_fips(state="California", county="Los Angeles County")
# => '06037'  → pass county="037" (last 3 digits)

6. changelog.md year "2026" for version 0.2

docs/reference/changelog.md:3 shows ## 0.2 (2026). If this version was released prior to 2026, the year should reflect the actual release date. If this is intentional (the library is being actively developed in 2026), it's fine, but worth verifying.

7. The moe column shows NaN for total-population state-level queries without explanation

In docs/guides/acs-data.md:53–58, the example output shows NaN for every moe value. This is factually correct for B01003_001 (population counts from the full-count Decennial base don't have MOE), but a brief note would save confusion for users who see NaN and assume something is broken.

---

Non-Documentation Changes

File	Change	Notes
pyproject.toml	Replaced mdx_include with mkdocs-material in docs extras	Correct — aligns with the new theme
README.md	Full rewrite to match new API	Clean and accurate
CONTRIBUTING.md	Updated dev setup instructions to use uv	Good
uv.lock	Lock file updated for new docs deps	Expected

---

Positive Highlights

• The progressive-disclosure structure in guides/margins-of-error.md (Level 1/2/3) is excellent for a mixed audience.
• The Mermaid decision tree in getting-started/census-101.md is a nice touch for helping users pick the right function.
• Side-by-side R/Python tabs in migration/from-tidycensus.md are exactly what R users need.
• The troubleshooting section in installation.md using ??? collapsible blocks keeps the page clean.
• Code annotation comments in quickstart.md are pedagogically great — once content.code.annotate is enabled they'll render beautifully.

[claude]

Claude finished @chekos's task in 1m 5s —— View job

---

Follow-up Review: Address PR Review Feedback

• Read CLAUDE.md and gather repo context
• Check if critical issue was fixed: content.code.annotate in mkdocs.yml
• Check if moderate issues were fixed: autorefs dep and pyproject.toml description
• Check if minor issues were addressed
• Post final review summary

---

All Issues from Previous Review Have Been Addressed ✅

The commit "Address all PR review feedback" resolves every item flagged in the prior review. Here's a verification:

Issue	Severity	Status
Missing content.code.annotate in mkdocs.yml	🔴 Critical	✅ Fixed — added at mkdocs.yml:17
mkdocs-autorefs not listed in pyproject.toml	🟡 Moderate	✅ Fixed — added at pyproject.toml:38
Outdated pyproject.toml description	🟡 Moderate	✅ Fixed — now reads "Python interface to the US Census Bureau API for ACS, Decennial Census, PUMS, population estimates, and migration flows."
Year inconsistency (2022 vs 2023)	🟢 Minor	✅ Fixed — docs/index.md:19 and README.md:21,35 all use year=2023
County FIPS lookup example missing	🟢 Minor	✅ Fixed — migration/from-tidycensus.md:38–49 has a lookup_fips() tip block
NaN MOE values unexplained	🟢 Minor	✅ Fixed — guides/acs-data.md:60–65 has an info admonition explaining this
changelog.md year "2026"	🟢 Minor	✅ N/A — today is 2026-03-09, so the year is correct

This PR is in good shape. The documentation overhaul is comprehensive and the feedback from the first review has been fully addressed.