docs: pull guide snippets from runnable, CI-tested example scripts

Previously every ```python fence in the guide was inline text. `zensical
build` only renders those fences, so a snippet that went stale against the
API would render fine while being broken — the guide's code was never
executed.

Move each snippet into a runnable script under examples/guide/ and include
it into the page with pymdownx.snippets (`--8<-- "examples/guide/<page>.py:
<section>"`), mirroring the substrait-java approach. Then:

- Enable pymdownx.snippets in zensical.toml with check_paths=true, so a bad
  include path or section name fails the docs build.
- Add tests/docs/test_guide_snippets.py, which executes every
  examples/guide/*.py end to end. Snippets that build a DataFrame call
  .to_plan(), so the test validates plan construction *and* resolution;
  this surfaced and fixed several previously-broken examples (e.g. joins
  referencing non-existent columns).
- Document the convention in CONTRIBUTING.md.
- The two engine-handoff snippets (DuckDB/ADBC tabs) stay inline: they need
  network + an external engine and are exercised by examples/{duckdb,adbc}_
  example.py (run by example.yml). Also add dataframe_example.py to that
  workflow's matrix (it was omitted).

Author: nielspardon

.github/workflows/example.yml

@@ -16,6 +16,7 @@ jobs:
       matrix:
         example:
           - builder_example.py
+          - dataframe_example.py
           - duckdb_example.py
           - adbc_example.py
           - pyarrow_example.py

CONTRIBUTING.md

@@ -43,3 +43,23 @@ When editing docstrings that appear in the reference, prefer Markdown (fenced
 code blocks and backticked names) over reStructuredText so they render cleanly.
 Every pull request runs a docs build-check; versioned docs are published to
 GitHub Pages on release (see `.github/workflows/docs-deploy.yml`).
+
+## Guide code snippets
+
+Code snippets in the guide are **not written inline**. Each `python` fence pulls
+its code from a runnable script under `examples/guide/` via
+[`pymdownx.snippets`](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/):
+
+````markdown
+```python
+--8<-- "examples/guide/<page>.py:<section>"
+```
+````
+
+The referenced code lives between `# --8<-- [start:<section>]` and
+`# --8<-- [end:<section>]` markers in that script. `tests/docs/test_guide_snippets.py`
+runs every `examples/guide/*.py` end to end, so a documented example that no longer
+builds a valid plan fails CI instead of silently rendering; `check_paths` in
+`zensical.toml` additionally fails the build if an include path or section name is
+wrong. To change a snippet, edit the `.py` file (adding a new `[start]`/`[end]`
+section for a new fence) rather than the Markdown.

docs/aggregations.md

@@ -6,20 +6,14 @@ Summarize rows with `group_by(...).agg(...)`. Aggregate functions come from the
 ## Group by and aggregate
 
 ```python
-import substrait.dataframe as sub
-
-df.group_by("region").agg(
-    sub.f.sum(sub.col("amount")).alias("total"),
-    sub.f.count(sub.col("amount")).alias("n"),
-)
+--8<-- "examples/guide/aggregations.py:group_agg"
 ```
 
 Group by multiple keys by passing several, and group the whole frame (a grand
 total) by passing none:
 
 ```python
-df.group_by("region", "product").agg(sub.f.sum(sub.col("amount")).alias("total"))
-df.group_by().agg(sub.f.count(sub.col("id")).alias("rows"))
+--8<-- "examples/guide/aggregations.py:multi_key_and_grand_total"
 ```
 
 `group_by` keys may be column names or expressions.
@@ -30,18 +24,15 @@ df.group_by().agg(sub.f.count(sub.col("id")).alias("rows"))
 the measures:
 
 ```python
-df.aggregate("region", sub.f.sum(sub.col("amount")).alias("total"))
-df.aggregate(["region", "product"], sub.f.count(sub.col("id")).alias("n"))
+--8<-- "examples/guide/aggregations.py:one_shot"
 ```
 
 ## Modifying a measure
 
 Aggregate measures support several modifiers, which chain:
 
 ```python
-sub.f.count(sub.col("customer")).distinct().alias("unique_customers")
-sub.f.sum(sub.col("amount")).filter(sub.col("status") == "paid").alias("paid_total")
-sub.f.string_agg(sub.col("name"), sub.lit(", ")).order_by("name").alias("names")
+--8<-- "examples/guide/aggregations.py:measure_modifiers"
 ```
 
 - **`.distinct()`** — operate on distinct inputs (`COUNT(DISTINCT x)`).
@@ -59,15 +50,7 @@ For multiple grouping levels in one aggregation, pass explicit `grouping_sets`
 shortcuts:
 
 ```python
-# explicit grouping sets: by (region, product), by (region), and the grand total
-df.group_by("region", "product", grouping_sets=[["region", "product"], ["region"], []]) \
-  .agg(sub.f.sum(sub.col("amount")).alias("total"))
-
-# ROLLUP: (region, product), (region), ()
-df.rollup("region", "product").agg(sub.f.sum(sub.col("amount")).alias("total"))
-
-# CUBE: every subset of the keys
-df.cube("region", "product").agg(sub.f.sum(sub.col("amount")).alias("total"))
+--8<-- "examples/guide/aggregations.py:grouping_sets"
 ```
 
 ## Next

docs/consuming-plans.md

@@ -9,16 +9,7 @@ substrait-python **produces** plans; it does not execute them. Once you have a
 into the bytes a consumer accepts:
 
 ```python
-import substrait.dataframe as sub
-
-plan = (
-    sub.read_named_table("customer", {"c_name": sub.string, "c_nationkey": sub.i32})
-    .filter(sub.col("c_nationkey") == 3)
-    .select("c_name")
-    .to_plan()
-)
-
-payload = plan.SerializeToString()
+--8<-- "examples/guide/consuming_plans.py:materialize"
 ```
 
 `DataFrame.to_substrait(registry=...)` is an alias kept for parity with the
@@ -31,9 +22,7 @@ The bundled pretty printer renders the plan as a compact tree — far more
 readable than the raw protobuf text:
 
 ```python
-from substrait.utils.display import pretty_print_plan
-
-pretty_print_plan(plan, use_colors=True)
+--8<-- "examples/guide/consuming_plans.py:pretty_print"
 ```
 
 ## Handing off to an engine
@@ -80,10 +69,7 @@ A serialized plan loads back with the generated protobuf class — useful for
 tests and for consuming plans other producers emit:
 
 ```python
-from substrait.proto import Plan
-
-restored = Plan()
-restored.ParseFromString(payload)
+--8<-- "examples/guide/consuming_plans.py:roundtrip"
 ```
 
 ## Relationship to Narwhals

docs/custom-extensions.md

@@ -13,19 +13,14 @@ across frames. To use custom functions, build your own registry and register
 extensions on it:
 
 ```python
-import substrait.dataframe as sub
-
-reg = sub.ExtensionRegistry(load_default_extensions=True)
-reg.register_extension_yaml("my_functions.yaml")   # from a YAML file
-# or, from an already-parsed dict (must contain a "urn" field):
-reg.register_extension_dict(definitions)
+--8<-- "examples/guide/custom_extensions.py:registry_setup"
 ```
 
 Pass the registry to a [source function](data-sources.md) so the whole chain
 uses it:
 
 ```python
-df = sub.read_named_table("t", {"x": sub.i64}, registry=reg)
+--8<-- "examples/guide/custom_extensions.py:pass_registry"
 ```
 
 ### Reaching custom functions by name
@@ -35,11 +30,7 @@ registry, build a bound namespace with `functions_for`, or use `df.f` (which is
 bound to that frame's registry automatically):
 
 ```python
-myf = sub.functions_for(reg)
-myf.my_double(sub.col("x"))
-
-# equivalently, off a frame built with `reg`:
-df.f.my_double(sub.col("x"))
+--8<-- "examples/guide/custom_extensions.py:reach_functions"
 ```
 
 See [The function namespace](functions.md) for more.
@@ -62,41 +53,15 @@ Each requires `to_any()`, `from_any(cls, detail)`, and `derive_schema(...)`, plu
 a `type_url` identifying the payload.
 
 ```python
-import substrait.dataframe as sub
-import substrait.type_pb2 as stt
-from google.protobuf.any_pb2 import Any
-
-
-class MyLeaf(sub.ExtensionLeafDetail):
-    type_url = "example.com/my.LeafDetail"
-
-    def to_any(self) -> Any:
-        payload = Any()
-        payload.type_url = self.type_url
-        # payload.value = ... serialize your fields ...
-        return payload
-
-    @classmethod
-    def from_any(cls, detail: Any) -> "MyLeaf":
-        return cls()  # ... deserialize your fields ...
-
-    def derive_schema(self) -> stt.NamedStruct:
-        return sub.named_struct(names=["x"], struct=sub.struct([sub.i64.non_null]))
+--8<-- "examples/guide/custom_extensions.py:detail_class"
 ```
 
 ### Building the relation
 
 Use the frame verbs / entry point matching the arity:
 
 ```python
-# leaf (a source): starts a new DataFrame
-df = sub.extension_leaf(MyLeaf())
-
-# single-input: applied to an existing frame
-df = base.extension(MySingle(...))
-
-# multi-input: this frame plus others
-df = base.extension_multi([other1, other2], MyMulti(...))
+--8<-- "examples/guide/custom_extensions.py:build_relation"
 ```
 
 `DataFrame.extension` also accepts a raw `google.protobuf.Any` directly, in
@@ -110,7 +75,7 @@ class — then inference reconstructs it from the plan's `Any` and calls
 `derive_schema`:
 
 ```python
-reg.register_extension_relation(MyLeaf)
+--8<-- "examples/guide/custom_extensions.py:register_relation"
 ```
 
 Registration is process-global (type URLs are globally unique), so inference

docs/data-sources.md

@@ -15,17 +15,13 @@ The most common source — a table the consumer resolves by name (a `ReadRel`
 with a `NamedTable`):
 
 ```python
-import substrait.dataframe as sub
-
-people = sub.read_named_table(
-    "people", {"id": sub.i64.non_null, "name": sub.string, "age": sub.i64}
-)
+--8<-- "examples/guide/data_sources.py:named_table"
 ```
 
 A multi-part name (catalog / schema / table) is given as a list:
 
 ```python
-sub.read_named_table(["main", "public", "people"], {"id": sub.i64})
+--8<-- "examples/guide/data_sources.py:multipart_name"
 ```
 
 ## Inline rows (VALUES)
@@ -35,14 +31,7 @@ like SQL `VALUES`. Rows may be dicts keyed by column name or positional
 sequences aligned to the schema; `None` becomes a typed null:
 
 ```python
-df = sub.from_records(
-    [
-        {"id": 1, "name": "Ada"},
-        {"id": 2, "name": "Alan"},
-        (3, None),  # positional; name is a typed null
-    ],
-    {"id": sub.i64.non_null, "name": sub.string},
-)
+--8<-- "examples/guide/data_sources.py:from_records"
 ```
 
 Each value is typed according to its schema column, so `from_records` is handy
@@ -54,20 +43,13 @@ Read local files by path (or a list of paths) plus a schema. These build a
 `ReadRel` over `LocalFiles`, one entry per path:
 
 ```python
-sub.read_parquet("data/events.parquet", {"ts": sub.i64, "kind": sub.string})
-sub.read_orc(["a.orc", "b.orc"], {"x": sub.i64})
-sub.read_arrow("table.arrow", {"x": sub.i64})
+--8<-- "examples/guide/data_sources.py:files"
 ```
 
 CSV/TSV reads take a couple of extra knobs:
 
 ```python
-sub.read_csv(
-    "data/people.csv",
-    {"id": sub.i64, "name": sub.string},
-    delimiter=",",          # use "\t" for TSV
-    header_lines_to_skip=1,  # skip the header row
-)
+--8<-- "examples/guide/data_sources.py:csv"
 ```
 
 !!! note "Schemas are declared, not inferred"
@@ -85,7 +67,7 @@ there are two extension entry points. Both are covered in detail under
   opaque `google.protobuf.Any` (`detail`). You still declare the output schema.
 
   ```python
-  sub.read_extension_table({"x": sub.i64}, my_any_detail)
+  --8<-- "examples/guide/data_sources.py:read_extension_table"
   ```
 
 - **`extension_leaf(detail)`** — a fully custom leaf relation
@@ -95,7 +77,7 @@ there are two extension entry points. Both are covered in detail under
   is needed.
 
   ```python
-  sub.extension_leaf(MyLeafDetail(...))
+  --8<-- "examples/guide/data_sources.py:extension_leaf"
   ```
 
 ## Next

docs/ddl-and-writes.md

@@ -10,15 +10,7 @@ materialize it.
 write operation and `mode` controls what happens when the table already exists:
 
 ```python
-import substrait.dataframe as sub
-
-summary = (
-    sub.read_named_table("orders", {"region": sub.string, "amount": sub.fp64})
-    .group_by("region")
-    .agg(sub.f.sum(sub.col("amount")).alias("total"))
-)
-
-plan = summary.write_named_table("region_totals", op="ctas", mode="replace").to_plan()
+--8<-- "examples/guide/ddl_and_writes.py:write_named_table"
 ```
 
 - **`op`** — `ctas` (create-table-as-select, default) or `insert`.
@@ -28,26 +20,15 @@ plan = summary.write_named_table("region_totals", op="ctas", mode="replace").to_
 ## Create table / view
 
 ```python
-# CREATE TABLE region_totals (region string, total fp64)
-sub.create_table("region_totals", {"region": sub.string, "total": sub.fp64})
-
-# CREATE OR REPLACE
-sub.create_table("region_totals", {"region": sub.string}, replace=True)
-
-# CREATE VIEW backed by a query (a DataFrame)
-big_orders = sub.read_named_table("orders", {"amount": sub.fp64}) \
-    .filter(sub.col("amount") > 1000)
-sub.create_view("big_orders", big_orders)
+--8<-- "examples/guide/ddl_and_writes.py:create_table_view"
 ```
 
 ## Drop table / view
 
 Pass `if_exists=True` for the `IF EXISTS` variant:
 
 ```python
-sub.drop_table("region_totals")
-sub.drop_table("region_totals", if_exists=True)
-sub.drop_view("big_orders", if_exists=True)
+--8<-- "examples/guide/ddl_and_writes.py:drop"
 ```
 
 ## Update
@@ -57,12 +38,7 @@ sub.drop_view("big_orders", if_exists=True)
 rows if omitted):
 
 ```python
-sub.update_table(
-    "orders",
-    {"id": sub.i64, "amount": sub.fp64, "status": sub.string},
-    assignments={"amount": sub.col("amount") * 1.1},
-    where=sub.col("status") == "pending",
-)
+--8<-- "examples/guide/ddl_and_writes.py:update"
 ```
 
 The schema you pass describes the target table so the assignment targets and