feat: add gallery_examples dataset mapping examples to datasets

.github/workflows/test.yml

@@ -36,6 +36,9 @@ jobs:
           uv run ruff check
           uv run ruff format --check
 
+      - name: Test (python)
+        run: uv run pytest
+
       - name: Install Node dependencies
         run: npm ci
 

CONTRIBUTING.md

@@ -50,6 +50,22 @@ For datasets requiring processing:
 - Ensure reproducibility with deterministic outputs and fixed random seeds when applicable
 - See `scripts/flights.py` as an example
 
+### Gallery Examples Registry
+
+The `data/gallery-examples.json` file catalogs examples from Vega, Vega-Lite, and Altair galleries, tracking which datasets each example uses.
+
+**When to regenerate:**
+- After new releases of Vega, Vega-Lite, or Altair that add/remove examples
+- When examples are renamed or reorganized upstream
+- Periodically (e.g., quarterly) to pick up new examples
+
+**Commands:**
+```bash
+uv run scripts/generate_gallery_examples.py         # Regenerate the file
+```
+
+Configuration lives in `_data/gallery_examples.toml` (source URLs). Runtime is ~45 seconds (async fetching of ~400 specs).
+
 ## Metadata and Documentation
 
 We follow the [Data Package Standard 2.0](https://datapackage.org/) with:
@@ -175,6 +191,9 @@ uv run taplo fmt --check --diff
 # Python linting and formatting
 uv run ruff check
 uv run ruff format --check
+
+# Python tests
+uv run pytest
 ```
 
 To automatically fix issues:
@@ -194,7 +213,7 @@ uv run ruff format
 
 3. Run checks and build:
    ```
-   uv run taplo fmt --check --diff && uv run ruff check && uv run ruff format --check
+   uv run taplo fmt --check --diff && uv run ruff check && uv run ruff format --check && uv run pytest
    npm run build
    ```
 

README.md

@@ -100,6 +100,8 @@ Visualizations built with these datasets are showcased in several galleries:
 - [Altair Example Gallery](https://altair-viz.github.io/gallery/index.html)
 - [Observable Vega Examples](https://observablehq.com/@vega)
 
+The [gallery-examples.json](data/gallery-examples.json) file maps gallery examples from Vega, Vega-Lite, and Altair to the datasets they use.
+
 ## Data Usage Note
 
 - The datasets are designed for instructional and demonstration purposes.

_data/datapackage_additions.toml

@@ -1888,3 +1888,71 @@ path  = "https://download.geonames.org/export/zip/"
 name  = "CC-BY-4.0"
 title = "Creative Commons Attribution 4.0 International"
 path  = "https://creativecommons.org/licenses/by/4.0/"
+
+# ==============================================================================
+# Gallery Examples Registry
+# ==============================================================================
+
+[[resources]]
+path = "gallery-examples.json"
+description = """Cross-reference mapping Vega, Vega-Lite, and Altair gallery examples
+to the vega-datasets resources they use. Each record links a gallery example to
+its datasets, categories, and source specification."""
+
+[[resources.sources]]
+title = "Vega Gallery"
+path  = "https://vega.github.io/vega/examples/"
+
+[[resources.sources]]
+title = "Vega-Lite Gallery"
+path  = "https://vega.github.io/vega-lite/examples/"
+
+[[resources.sources]]
+title = "Altair Gallery"
+path  = "https://altair-viz.github.io/gallery/"
+
+[[resources.licenses]]
+name  = "BSD-3-Clause"
+title = "The 3-Clause BSD License"
+path  = "https://opensource.org/license/bsd-3-clause"
+
+[resources.schema]
+primaryKey = "spec_url"
+
+[[resources.schema.fields]]
+name        = "gallery_name"
+type        = "string"
+description = "Name of the gallery this example belongs to"
+constraints = { enum = ["vega", "vega-lite", "altair"] }
+
+[[resources.schema.fields]]
+name        = "example_name"
+type        = "string"
+description = "Human-readable example title"
+
+[[resources.schema.fields]]
+name        = "example_url"
+type        = "string"
+description = "URL to rendered example in the gallery"
+
+[[resources.schema.fields]]
+name        = "spec_url"
+type        = "string"
+description = "URL to source specification or code"
+
+[[resources.schema.fields]]
+name        = "categories"
+type        = "array"
+description = "Tags or categories for the example (e.g., 'Bar Charts', 'Interactive')"
+
+[[resources.schema.fields]]
+name        = "description"
+type        = "string"
+description = "Optional description of what the example demonstrates (may be null)"
+constraints = { required = false }
+
+[[resources.schema.fields]]
+name        = "datasets"
+type        = "array"
+description = "Dataset names referencing resource.name in this package"
+

_data/gallery_examples.toml

@@ -0,0 +1,4 @@
+[sources]
+vega_lite_examples_url = "https://raw.githubusercontent.com/vega/vega-lite/main/site/_data/examples.json"
+vega_examples_url = "https://raw.githubusercontent.com/vega/vega/main/docs/_data/examples.json"
+altair_examples_dir = "tests/examples_methods_syntax"