Complete documentation overhaul

CONTRIBUTING.md

@@ -1,33 +1,37 @@
-# How to contribute
-To contribute to this library, first checkout the code. Then create a new virtual environment:
+# How to Contribute
 
-    cd pypums
-    python -m venv venv
-    source venv/bin/activate
+To contribute to this library, first checkout the code. Then install [uv](https://docs.astral.sh/uv/) and set up the project:
 
-Or if you are using `pipenv`:
+```bash
+cd pypums
+uv sync --extra test
+```
 
-    pipenv shell
-
-Now install the dependencies and test dependencies:
+To run the tests:
 
-    pip install -e '.[test]'
+```bash
+uv run pytest
+```
 
-To run the tests:
+To run the linter:
 
-    pytest
+```bash
+uvx ruff check .
+uvx ruff format --check .
+```
 
-### Before submitting
+## Before Submitting
 
 Before submitting your code please do the following steps:
 
 1. Add any changes you want
-1. Add tests for the new changes
-1. Edit documentation if you have changed something significant
+2. Add tests for the new changes
+3. Edit documentation if you have changed something significant
+4. Make sure all tests pass with `uv run pytest`
+5. Make sure code style is clean with `uvx ruff check .`
+
+## Other Help
 
-## Other help
+You can contribute by spreading a word about this library. It would also be a huge contribution to write a short article on how you are using this project. You can also share your best practices with us.
 
-You can contribute by spreading a word about this library.
-It would also be a huge contribution to write
-a short article on how you are using this project.
-You can also share your best practices with us.
+See the full [contributing guide](https://chekos.github.io/pypums/about/contributing/) for more details.

README.md

@@ -1,56 +1,128 @@
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/chekos/pypums/HEAD?labpath=examples%2Fnb-example.ipynb)
+# PyPUMS
 
-# pypums
+**Python interface to the US Census Bureau API** — American Community Survey, Decennial Census, PUMS microdata, population estimates, and migration flows.
 
-[![Build status](https://github.com/chekos/pypums/workflows/build/badge.svg?branch=master&event=push)](https://github.com/chekos/pypums/actions?query=workflow%3Abuild)
-[![Changelog](https://img.shields.io/github/v/release/chekos/pypums?include_prereleases&label=changelog)](https://github.com/chekos/pypums/releases)
-[![License](https://img.shields.io/github/license/chekos/pypums)](https://github.com/chekos/pypums/blob/master/LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/pypums)](https://pypi.org/project/pypums/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pypums)](https://pypi.org/project/pypums/)
+[![License](https://img.shields.io/github/license/chekos/pypums)](https://github.com/chekos/pypums/blob/main/LICENSE)
+[![Build status](https://github.com/chekos/pypums/workflows/build/badge.svg)](https://github.com/chekos/pypums/actions?query=workflow%3Abuild)
 
-Download Public Use Micro Sample (PUMS) data files from the US Census Bureau's FTP server.
+## Quick Start
 
-## Usage
+Get county-level median household income for California:
 
-To use PyPUMS in a project:
+```python
+import pypums
 
-![on a jupyter notebook](https://github.com/chekos/pypums/blob/main/docs/static/usage.gif?raw=true)
+df = pypums.get_acs(
+    geography="county",
+    variables=["B19013_001"],
+    state="CA",
+    year=2023,
+)
+df.head()
+```
+
+Make a map with tract-level data:
+
+```python
+df = pypums.get_acs(
+    geography="tract",
+    variables=["B19013_001"],
+    state="CA",
+    county="037",
+    year=2023,
+    geometry=True,  # returns a GeoDataFrame
+)
+df.plot(column="estimate", legend=True, figsize=(12, 8))
+```
+
+Work with PUMS microdata:
+
+```python
+pums = pypums.get_pums(
+    variables=["AGEP", "SEX", "WAGP"],
+    state="CA",
+    year=2023,
+    recode=True,  # adds human-readable labels
+)
+pums.head()
+```
 
-or as a CLI
+## Features
 
-![as a CLI](https://github.com/chekos/pypums/blob/main/docs/static/cli.gif?raw=true)
+- **`get_acs()`** — American Community Survey data (1-year and 5-year)
+- **`get_decennial()`** — Decennial Census data (2000, 2010, 2020)
+- **`get_pums()`** — PUMS microdata with replicate weight support
+- **`get_estimates()`** — Population Estimates Program data
+- **`get_flows()`** — ACS migration flows (county and MSA level)
+- **`load_variables()`** — Search and browse Census variable codes
+- **MOE functions** — `moe_sum()`, `moe_ratio()`, `moe_prop()`, `moe_product()`, `significance()`
+- **Spatial support** — Attach TIGER/Line geometries, returns GeoDataFrames
+- **Survey design** — `SurveyDesign` class with successive difference replication
+- **Caching** — File-based caching with configurable TTL
+- **CLI** — Command-line access to all data functions
 
 ## Installation
 
-Install this library using `pip`:
+```bash
+pip install pypums
+```
 
-    pip install pypums
+For spatial/mapping support:
 
-## Usage
+```bash
+pip install "pypums[spatial]"
+```
 
-Usage instructions go here.
+## Census API Key
+
+You need a free Census API key. [Request one here](https://api.census.gov/data/key_signup.html), then:
+
+```bash
+export CENSUS_API_KEY="your-key-here"
+```
+
+Or set it in Python:
+
+```python
+import pypums
+pypums.census_api_key("your-key-here")
+```
+
+## Documentation
+
+Full documentation: [https://chekos.github.io/pypums](https://chekos.github.io/pypums)
 
 ## Development
 
 To contribute to this library, first checkout the code. Then install [uv](https://docs.astral.sh/uv/) and set up the project:
 
-    cd pypums
-    uv sync --extra test
+```bash
+cd pypums
+uv sync --extra test
+```
 
 To run the tests:
 
-    uv run pytest
+```bash
+uv run pytest
+```
 
 To run the linter:
 
-    uvx ruff check .
-    uvx ruff format --check .
+```bash
+uvx ruff check .
+uvx ruff format --check .
+```
 
-## 📃 Citation
+## Citation
 
 ```
 @misc{pypums,
-  author = {chekos},
-  title = {Download Public Use Micro Sample (PUMS) data files from the US Census Bureau's FTP server.},
-  year = {2020},
+  author = {Sergio Sanchez Zavala},
+  title = {PyPUMS: Python interface to the US Census Bureau API},
+  year = {2019},
   publisher = {GitHub},
   journal = {GitHub repository},
   howpublished = {\url{https://github.com/chekos/pypums}}

docs/about/authors.md

@@ -1,12 +1,9 @@
-Credits
-=======
+# Authors
 
-Development Lead
-----------------
+## Development Lead
 
--   Sergio Sánchez Zavala <<sergio@cimarron.io>>
+- **Sergio Sanchez Zavala** — [github.com/chekos](https://github.com/chekos)
 
-Contributors
-------------
+## Contributors
 
-None yet. Why not be the first?
+- [@yonran](https://github.com/yonran) — Bug fixes and improvements (v0.0.7)