Updated and organized ipynb examples directory for clarity

.github/workflows/build.yml

@@ -285,7 +285,8 @@ jobs:
         working-directory: lite
         run: |
           set -eux
-          mkdir -p content && cp ../examples/*.jGIS ../examples/*.qgz ../examples/*.geojson ../examples/*.tif ../examples/*.zip ../examples/*.ipynb ../examples/*.gif ./content
+          cp --recursive --dereference ../ui-tests/content ./content
+          find ./content -type d -name ".ipynb_checkpoints" -exec rm -rf {} +
           jupyter lite build --contents content --output-dir dist
 
       - name: Upload Lite artifacts

docs/conf.py

@@ -35,13 +35,7 @@
 language = "en"
 
 jupyterlite_contents = [
-    "../examples/*.jGIS",
-    "../examples/*.geojson",
-    "../examples/*.zip",
-    "../examples/*.gif",
-    "../examples/*.geojson",
-    "../examples/*.tif",
-    "../examples/*.ipynb",
+    "../examples",
 ]
 jupyterlite_dir = "."
 jupyterlite_config = "jupyter_lite_config.json"

examples/01-Create_a_new_JGIS_document.ipynb

@@ -0,0 +1,105 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "8dbc9440",
+   "metadata": {},
+   "source": [
+    "## What is \"The Map\" in a Geographic Information System (GIS) context?\n",
+    "\n",
+    "In traditional geography, a **map** is a picture that shows the layout of some part of the world — things like roads, rivers, buildings, or population data, all drawn at a certain scale and intended to illustrate or enable something specific.\n",
+    "\n",
+    "But in **digital mapping** (or Geographic Information Systems, GIS), a map is much more than just a picture — it's made up of **data** that can be viewed, edited, analyzed, and combined with other data.\n",
+    "\n",
+    "In GIS software like **JupyterGIS**, a digital map is actually a **document** that holds:\n",
+    "\n",
+    "- **Layers** — These are pieces of data, like roads, rivers, or land use. Each layer represents one kind of thing or phenomenon, in the physical world.\n",
+    "- **Basemaps** — These are background images, like satellite imagery or street maps, that help give context to your data layers.\n",
+    "- **Tools** — Things that let you analyze or edit the layers on your map.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## Dana Tomlin's Cartographic Model (Simplified)\n",
+    "\n",
+    "In his foundational work [GIS & Cartographic Modeling](https://archive.org/details/geographicinform00toml), Dana Tomlin, one of the founders of modern GIS, described the **Cartographic Model** as a way to think of maps not just as images, but as **tools for thinking and analysis**.\n",
+    "\n",
+    "In his model:\n",
+    "> A map is not just a picture of the world, but a **set of layers of data** that can be combined using logic and rules.\n",
+    "\n",
+    "In other words, each layer on the map has meaning — and by combining layers in specific ways we can answer questions like:\n",
+    "- Where is the best place to build a school?\n",
+    "- Which areas are at risk of flooding?\n",
+    "- How has a city's land use changed over time?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "639b7342-688d-47c6-be9f-d4f7e60b74e7",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "from jupytergis import GISDocument\n",
+    "\n",
+    "# Create a new GIS document (a digital map)\n",
+    "doc = GISDocument(\"local.jGIS\")\n",
+    "\n",
+    "# Display the map document in the notebook\n",
+    "doc"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1c58c922",
+   "metadata": {},
+   "source": [
+    "### What does this code do?\n",
+    "\n",
+    "1. `from jupytergis import GISDocument`\n",
+    "   This line tells Python to load the `GISDocument` module from the `jupytergis` library. Think of the `GISDocument` module as the part of the pre-written JupyterGIS code that creates your digital map container in the notebook.\n",
+    "\n",
+    "2. `doc = GISDocument(\"local.jGIS\")`\n",
+    "   This defines a variable called `doc` to store the command that will import the file `local.jGIS` as the `GISDocument`.\n",
+    "   This document is where you'll add your layers (roads, rivers, buildings, etc.) and tools.\n",
+    "\n",
+    "3. `doc`\n",
+    "   When you type this in a notebook cell and run it, it runs the module `GISDocument` to create an interactive map in your notebook, using the `local.jGIS` file. You can then later add layers, change the basemap, and do spatial analysis. You *could* use the complete command `GISDocument(\"local.jGIS\")` to run the GISModule, but storing the command in a short variable (like, `doc`) allows you to easily reuse the command, with less text, in your code. \n",
+    "\n",
+    "---\n",
+    "\n",
+    "### Summary\n",
+    "\n",
+    "So far, you've created the **foundation** of your GIS project — a digital **Map Document** that can hold multiple layers and allow you to explore and analyze spatial data.\n",
+    "\n",
+    "This is like opening a new document in Word or Google Docs — but instead of writing an essay, you're going to build and explore a map!"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.18"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/explore.ipynb → examples/99-Explore_data_in_a_map.ipynb

@@ -3,24 +3,50 @@
   {
    "cell_type": "markdown",
    "id": "c3f4096f-cbd3-43e8-a986-520681f03581",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "# ESPM 157 - Intro to Spatial Data\n",
     "\n",
     "<https://espm-157.carlboettiger.info/spatial-1>\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0d1dbcb0",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "# Install dependencies:\n",
     "\n",
-    "Install dependencies:\n",
-    "\n",
-    "```bash\n",
-    "micromamba install geopandas ibis-duckdb\n",
-    "```"
+    "#!conda install geopandas ibis-framework\n",
+    "!mamba install geopandas ibis-framework -y"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "b76ae1f0-334e-41c0-9533-407c879b4ad6",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "import ibis\n",
@@ -32,7 +58,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "837aa4e0-5eeb-48c1-97ce-3f8706503911",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "redlines = con.read_geo(\n",
@@ -44,7 +76,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "4d3319fa-b3b4-4931-b073-98b649e41b65",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "city = redlines.filter(redlines.city == \"New Haven\")"
@@ -55,7 +93,12 @@
    "execution_count": null,
    "id": "34f7f4d6-28d6-4716-8e03-ac32c6ae3bb7",
    "metadata": {
-    "scrolled": true
+    "editable": true,
+    "scrolled": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
    },
    "outputs": [],
    "source": [
@@ -66,7 +109,13 @@
   {
    "cell_type": "markdown",
    "id": "d37a610a-1444-43a3-900f-dfe16a890ab9",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "## OK, but what about spatial context?\n",
     "\n",
@@ -77,7 +126,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "6e68aaac-dfc0-42d8-a3b9-05fce59524b2",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "from jupytergis import explore\n",
@@ -103,7 +158,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.9"
+   "version": "3.10.18"
   }
  },
  "nbformat": 4,