Run the tutorial notebooks at build time when a key is present

Author: Nathaniel Henry

.github/workflows/docs.yml

@@ -23,7 +23,11 @@ jobs:
         with:
           python-version: "3.12"
       - run: pip install -e ".[docs]"
+      # Set this repo secret to run the tutorial notebooks and render their output
+      # and maps. Without it, the notebooks are shown but not executed.
       - run: sphinx-build -b html docs docs/_build/html -W --keep-going
+        env:
+          CLOSECITY_KEY: ${{ secrets.CLOSECITY_KEY }}
       - uses: actions/upload-pages-artifact@v3
         with:
           path: docs/_build/html

docs/conf.py

@@ -1,10 +1,11 @@
 """Sphinx configuration for the closecity Python documentation."""
 
 import importlib.metadata
+import os
 
 project = "closecity"
-author = "Close"
-copyright = "2026, Close"  # noqa: A001
+author = "Nathaniel Henry"
+copyright = "2026, Henry Spatial Analysis"  # noqa: A001
 try:
     release = importlib.metadata.version("closecity")
 except importlib.metadata.PackageNotFoundError:
@@ -16,9 +17,20 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
+    "myst_nb",
 ]
 
-# httpx is the only runtime dep; mock it so the docs build without installing it.
+# The getting-started and tutorial pages are executable notebooks. Run them when a
+# key is present (on the docs site), and show the code without running it otherwise.
+nb_execution_mode = "auto" if os.environ.get("CLOSECITY_KEY") else "off"
+nb_execution_timeout = 180
+nb_execution_raise_on_error = True
+
+# When the notebooks are not executed (no key), myst-nb cannot infer a highlight
+# language for the code cells and warns once per cell. The cells still render with
+# python highlighting from the code-cell directive, so silence that one warning.
+suppress_warnings = ["myst-nb.lexer"]
+
 autodoc_mock_imports = ["httpx"]
 autodoc_member_order = "bysource"
 # The SDK docstrings are plain reStructuredText prose with single-backtick

docs/getting_started.md

@@ -0,0 +1,95 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+
+# Getting started
+
+A short tour of the client. The tutorials go further.
+
+```{code-cell} python
+:tags: [remove-cell]
+import os
+from closecity import Client
+close = Client(os.environ.get("CLOSECITY_KEY"))
+```
+
+## Words you will see
+
+A few terms come up throughout:
+
+- **Census block.** The smallest area the Census Bureau publishes. Each one has a
+  15-digit id, its **GEOID**.
+- **Destination type.** A category of place, such as grocery stores or libraries.
+  Every type has a numeric id.
+- **Mode.** How someone travels: walk, bike, or transit.
+- **Isochrone.** The area reachable from a point within a time limit, as a polygon.
+- **Catchment.** The reverse: every block that can reach a given place.
+
+## Build a client
+
+You make every request through a client.
+
+```python
+from closecity import Client
+
+close = Client("ck_live_your_key")   # use your own key here
+```
+
+The catalog and lookup routes are free, so `Client()` with no key works for those.
+
+```{code-cell} python
+close.modes().data["modes"]
+```
+
+## Look things up instead of guessing
+
+Read the numeric id for a category from the catalog, and turn a city name into a
+GEOID and a centre point.
+
+```{code-cell} python
+types = close.destination_types().data["destination_types"]
+ids = {t["label"]: t["dest_type_id"] for t in types}
+grocery = ids["grocery_stores"]
+
+providence = close.places("Providence").data["places"][0]
+providence["geoid"]
+```
+
+## Make a call and map it
+
+Feature methods return a GeoDataFrame, so you can map the result straight away.
+
+```{code-cell} python
+groceries = close.pois_search(lat = providence["lat"], lon = providence["lon"],
+                              radius_m = 1500, type = grocery)
+groceries.plot(color = "#202a5b")
+```
+
+## Turn spatial output off
+
+Set the client's `spatial` flag to `False` to work with the raw data.
+
+```{code-cell} python
+close.spatial = False
+summary = close.block_summary("440070036001010", mode = "walk")
+summary.results
+```
+
+## Errors
+
+Problem responses become typed exceptions.
+
+```{code-cell} python
+from closecity import CloseAPIError
+
+try:
+    close.block_summary("000000000000000")
+except CloseAPIError as err:
+    print(err.status, err.slug)
+```

docs/getting_started.rst

@@ -0,0 +1,130 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+
+# The amenity basket
+
+A city planner wants every resident to be able to walk to a basket of six everyday
+amenities: a grocery store, a library, a park, a frequent-transit stop, a restaurant,
+and a cafe. This tutorial measures how many residents already have that, and shows
+where the gaps are. The idea follows
+[this analysis](https://nathenry.com/writing/2023-02-07-seattle-walkability.html),
+here applied to Richmond, Virginia.
+
+```{code-cell} python
+:tags: [remove-cell]
+import os
+from closecity import Client
+close = Client(os.environ.get("CLOSECITY_KEY"))
+```
+
+## Set up
+
+Read the six category ids from the free catalog, and turn the city name into a centre
+point.
+
+```python
+from closecity import Client
+
+close = Client("ck_live_your_key")   # use your own key here
+```
+
+```{code-cell} python
+types = close.destination_types().data["destination_types"]
+ids = {t["label"]: t["dest_type_id"] for t in types}
+basket = {
+    "grocery": ids["grocery_stores"],
+    "library": ids["libraries"],
+    "park": ids["parks"],
+    "transit": ids["frequent_transit"],
+    "restaurant": ids["restaurants"],
+    "cafe": ids["cafes"],
+}
+
+city = close.places("Richmond").data["places"][0]
+```
+
+## Pull the blocks, with population
+
+One call gets the walk time from every block near downtown to each of the six
+categories, along with each block's population.
+
+```{code-cell} python
+blocks = close.blocks_query(
+    center = {"lon": city["lon"], "lat": city["lat"]}, radius_m = 2500,
+    mode = "walk", type = list(basket.values()), include_population = True)
+
+one_per_block = blocks.drop_duplicates("geoid")
+total_pop = one_per_block["population"].sum()
+```
+
+## Coverage, one amenity at a time
+
+For each amenity, a block counts as covered when it is within a 15-minute walk.
+
+```{code-cell} python
+for name, type_id in basket.items():
+    covered = set(blocks.loc[(blocks.dest_type_id == type_id) &
+                             (blocks.travel_time <= 15), "geoid"])
+    pop = one_per_block.loc[one_per_block.geoid.isin(covered), "population"].sum()
+    print(f"{name:11} {100 * pop / total_pop:3.0f}%")
+```
+
+Map one amenity to see the pattern.
+
+```{code-cell} python
+near_transit = set(blocks.loc[(blocks.dest_type_id == basket["transit"]) &
+                              (blocks.travel_time <= 15), "geoid"])
+one_per_block = one_per_block.assign(
+    has_transit = one_per_block.geoid.isin(near_transit))
+one_per_block.plot(column = "has_transit", cmap = "Greens")
+```
+
+## Who can reach all six
+
+A block is fully covered only if all six amenities are within 15 minutes.
+
+```{code-cell} python
+covered_all = set(one_per_block.geoid)
+for type_id in basket.values():
+    covered = set(blocks.loc[(blocks.dest_type_id == type_id) &
+                             (blocks.travel_time <= 15), "geoid"])
+    covered_all &= covered
+
+basket_pop = one_per_block.loc[one_per_block.geoid.isin(covered_all),
+                               "population"].sum()
+print(f"All six amenities: {100 * basket_pop / total_pop:.0f}% of residents")
+
+one_per_block = one_per_block.assign(
+    full_basket = one_per_block.geoid.isin(covered_all))
+one_per_block.plot(column = "full_basket", cmap = "Oranges")
+```
+
+## Which amenity to add first
+
+Count how many not-yet-covered residents are missing each amenity. The amenity the
+most people lack is the one to add first.
+
+```{code-cell} python
+uncovered = set(one_per_block.geoid) - covered_all
+for name, type_id in basket.items():
+    covered = set(blocks.loc[(blocks.dest_type_id == type_id) &
+                             (blocks.travel_time <= 15), "geoid"])
+    lacking = uncovered - covered
+    pop = one_per_block.loc[one_per_block.geoid.isin(lacking), "population"].sum()
+    print(f"{name:11} {pop:6.0f} residents would gain access")
+```
+
+Map the uncovered blocks to see where new amenities would do the most good.
+
+```{code-cell} python
+one_per_block = one_per_block.assign(
+    uncovered = one_per_block.geoid.isin(uncovered))
+one_per_block.plot(column = "uncovered", cmap = "Blues")
+```