loom-kernel 0.4.0__tar.gz → 0.6.0__tar.gz

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/.github/workflows/ci-main.yml

@@ -88,7 +88,7 @@ jobs:
           uv export --frozen --only-group dev --no-hashes --no-emit-project \
             -o "$MANIFEST_DIR/requirements-dev.txt"
 
-          for extra in rest sqlalchemy config cache pyspark prometheus celery; do
+          for extra in rest sqlalchemy config cache pyspark prometheus celery streaming; do
             uv export --frozen --no-default-groups --no-dev --extra "$extra" \
               --no-hashes --no-emit-project \
               -o "$MANIFEST_DIR/requirements-extra-${extra}.txt"
@@ -103,7 +103,7 @@ jobs:
             --file="$MANIFEST_DIR/requirements-dev.txt" --package-manager=pip \
             --project-name="loom-py/dev" --target-reference="${GITHUB_REF_NAME:-master}"
 
-          for extra in rest sqlalchemy config cache pyspark prometheus celery; do
+          for extra in rest sqlalchemy config cache pyspark prometheus celery streaming; do
             python -m pip install -r "$MANIFEST_DIR/requirements-extra-${extra}.txt"
             snyk monitor --skip-unresolved \
               --file="$MANIFEST_DIR/requirements-extra-${extra}.txt" \

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/.github/workflows/ci-pr.yml

@@ -142,7 +142,7 @@ jobs:
           uv export --frozen --only-group dev --no-hashes --no-emit-project \
             -o "$MANIFEST_DIR/requirements-dev.txt"
 
-          for extra in rest sqlalchemy config cache pyspark prometheus celery; do
+          for extra in rest sqlalchemy config cache pyspark prometheus celery streaming; do
             uv export --frozen --no-default-groups --no-dev --extra "$extra" \
               --no-hashes --no-emit-project \
               -o "$MANIFEST_DIR/requirements-extra-${extra}.txt"
@@ -162,7 +162,7 @@ jobs:
             --package-manager=pip \
             --project-name="loom-py/dev"
 
-          for extra in rest sqlalchemy config cache pyspark prometheus celery; do
+          for extra in rest sqlalchemy config cache pyspark prometheus celery streaming; do
             python -m pip install -r "$MANIFEST_DIR/requirements-extra-${extra}.txt"
             snyk test --severity-threshold=high \
               --skip-unresolved \

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/.gitignore

@@ -16,6 +16,7 @@ wheels/
 coverage.xml
 htmlcov/
 .vscode/
+.pi/
 docs/__pycache__/
 .claude/
 .claude.md

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/CHANGELOG.md

@@ -1,3 +1,148 @@
+# 🚀 Release 0.6.0 ([#22](https://github.com/the-reacher-data/loom-py/pull/22)) ([`5146569`](https://github.com/the-reacher-data/loom-py/commit/51465697115036ed05f620a1099272e4fd216501))
+
+
+## ✨ Features
+### core
+- **core:** add unified ObservabilityRuntime<br>
+  > Introduces the core observability package: LifecycleEvent, LifecycleObserver
+  > protocol, ObservabilityConfig, and ObservabilityRuntime as a single fan-out
+  > engine replacing the fragmented per-module observer wiring. Adds
+  > StructlogLifecycleObserver, OtelLifecycleObserver, NoopObserver, and
+  > PrometheusLifecycleAdapter (with Pushgateway support for ETL batch jobs).
+  > Backward-compat re-exports (safe_observe, notify_observers) kept for the
+  > streaming composite observer until the legacy cleanup commit.
+
+
+
+## 🐛 Fixes
+### observability
+- **observability:** restore default bootstraps
+
+### rest
+- **rest:** correct camel-to-snake conversion for acronyms in filter fields
+
+### streaming
+- **streaming:** propagate trace ids through bytewax paths
+- **streaming:** keep input trace ids through the micro
+- **streaming:** bridge otel trace ids from messages
+
+
+## 📖 Documentation
+- align yaml config and dummy repo links
+- restore dummy repo urls
+- fix markdown links for streaming dummies
+
+### prometheus
+- **prometheus:** update KafkaPrometheusMetrics docstring metric names
+
+
+
+## ♻️ Refactor
+### observability
+- **observability:** simplify otel log correlation
+- **observability:** simplify otel exporter imports
+- **observability:** expose ObservabilityRuntime in public API and clean architecture debt<br>
+  > Export ObservabilityRuntime and LifecycleStatus from loom.core.observability package
+  > Compute dict(meta) once in span() instead of three separate allocations
+  > Replace _SIGNALS_CONNECTED module-level global with ClassVar on _CeleryAsyncRuntime
+  > Add RuntimeError to bootstrap_worker Raises docstring
+  > Fix TraceIdMiddleware docstring example (removed spurious ObservabilityRuntime reference)
+  > Add missing observability_runtime param to _make_handler docstring
+
+- **observability:** unify runtime across services
+- **observability:** clean up dead code and docs
+
+### streaming
+- **streaming:** migrate to unified ObservabilityRuntime<br>
+  > Replace StreamingObservabilityConfig and the manual observer construction
+  > in _load_observability_runtime() with ObservabilityRuntime.from_config().
+  > Observability config now lives under streaming.runtime.observability in YAML,
+  > eliminating the separate streaming.observability section.
+  > Delete src/loom/streaming/_observability.py (StreamingObservabilityConfig)
+  > Delete src/loom/streaming/observability/ directory (old observer stack)
+  > Add observability: ObservabilityConfig field to BytewaxRuntimeConfig
+  > StreamingRunner.from_config() calls ObservabilityRuntime.from_config() directly
+  > StreamingTestRunner defaults to ObservabilityRuntime.noop(); callers pass
+  > observability_runtime= explicitly when needed
+  > Update tests to use new config shape and ObservabilityRuntime([observer])
+
+- **streaming:** replace KafkaStreamingObserver with LifecycleEvent/TRANSPORT<br>
+  > Eliminates the parallel KafkaStreamingObserver protocol hierarchy (NoopKafkaObserver,
+  > StructlogKafkaObserver) and models all Kafka transport events as LifecycleEvent with
+  > Scope.TRANSPORT. KafkaPrometheusMetrics now implements the LifecycleObserver protocol
+  > via a single on_event() dispatcher instead of four typed callback methods.
+
+- **streaming:** preserve trace lineage across boundaries
+
+### prometheus
+- **prometheus:** add KafkaMetricName enum and drop loom_ prefix<br>
+  > Extracts Prometheus metric names into a public KafkaMetricName StrEnum so
+  > callers can reference metric names without magic strings. Removes the loom_
+  > namespace prefix from all four Kafka instruments (produced_total,
+  > consumed_total, encode_duration_seconds, decode_duration_seconds).
+
+- **prometheus:** drop loom prefix from lifecycle metrics
+
+### rest
+- **rest:** use core observability runtime
+- **rest:** read prometheus from observability config
+
+### celery
+- **celery:** adopt async bridge and runtime config
+
+### etl
+- **etl:** make spark pytest plugin opt-in
+
+
+
+## ✅ Tests
+### kafka
+- **kafka:** update metric name assertions after loom_ prefix removal
+
+### observability
+- **observability:** cover lineage and runtime branches
+
+### integration
+- **integration:** add in-memory REST, observability, and bootstrap integration tests
+
+### etl
+- **etl:** cover prometheus flush on runner shutdown
+
+
+## 🛠 Chores
+### deps
+- **deps:** bump click to 8.3.3
+
+
+
+
+# 🚀 Release 0.5.0 ([#20](https://github.com/the-reacher-data/loom-py/pull/20)) ([`70f7cf8`](https://github.com/the-reacher-data/loom-py/commit/70f7cf85275fcc1f590e06f980dfac91cad50893))
+
+
+## ✨ Features
+### core
+- **core:** add shared expression routing primitives
+
+### streaming
+- **streaming:** add process DSL and routing
+- **streaming:** add kafka transport and observability
+- **streaming:** allow task resource kwargs
+- **streaming:** add scoped dependency nodes
+- **streaming:** make tasks configurable
+
+### config
+- **config:** add declarative config bindings
+
+
+
+
+
+
+
+
+
+
+
 # 🚀 Release 0.4.0 ([#18](https://github.com/the-reacher-data/loom-py/pull/18)) ([`09e5aa3`](https://github.com/the-reacher-data/loom-py/commit/09e5aa340f88e0488daca2bf10320aad7aebbe1d))
 
 

loom_kernel-0.6.0/CHANGELOG_RELEASE.md

@@ -0,0 +1,116 @@
+# 🚀 Release 0.6.0 ([#22](https://github.com/the-reacher-data/loom-py/pull/22)) ([`5146569`](https://github.com/the-reacher-data/loom-py/commit/51465697115036ed05f620a1099272e4fd216501))
+
+
+## ✨ Features
+### core
+- **core:** add unified ObservabilityRuntime<br>
+  > Introduces the core observability package: LifecycleEvent, LifecycleObserver
+  > protocol, ObservabilityConfig, and ObservabilityRuntime as a single fan-out
+  > engine replacing the fragmented per-module observer wiring. Adds
+  > StructlogLifecycleObserver, OtelLifecycleObserver, NoopObserver, and
+  > PrometheusLifecycleAdapter (with Pushgateway support for ETL batch jobs).
+  > Backward-compat re-exports (safe_observe, notify_observers) kept for the
+  > streaming composite observer until the legacy cleanup commit.
+
+
+
+## 🐛 Fixes
+### observability
+- **observability:** restore default bootstraps
+
+### rest
+- **rest:** correct camel-to-snake conversion for acronyms in filter fields
+
+### streaming
+- **streaming:** propagate trace ids through bytewax paths
+- **streaming:** keep input trace ids through the micro
+- **streaming:** bridge otel trace ids from messages
+
+
+## 📖 Documentation
+- align yaml config and dummy repo links
+- restore dummy repo urls
+- fix markdown links for streaming dummies
+
+### prometheus
+- **prometheus:** update KafkaPrometheusMetrics docstring metric names
+
+
+
+## ♻️ Refactor
+### observability
+- **observability:** simplify otel log correlation
+- **observability:** simplify otel exporter imports
+- **observability:** expose ObservabilityRuntime in public API and clean architecture debt<br>
+  > Export ObservabilityRuntime and LifecycleStatus from loom.core.observability package
+  > Compute dict(meta) once in span() instead of three separate allocations
+  > Replace _SIGNALS_CONNECTED module-level global with ClassVar on _CeleryAsyncRuntime
+  > Add RuntimeError to bootstrap_worker Raises docstring
+  > Fix TraceIdMiddleware docstring example (removed spurious ObservabilityRuntime reference)
+  > Add missing observability_runtime param to _make_handler docstring
+
+- **observability:** unify runtime across services
+- **observability:** clean up dead code and docs
+
+### streaming
+- **streaming:** migrate to unified ObservabilityRuntime<br>
+  > Replace StreamingObservabilityConfig and the manual observer construction
+  > in _load_observability_runtime() with ObservabilityRuntime.from_config().
+  > Observability config now lives under streaming.runtime.observability in YAML,
+  > eliminating the separate streaming.observability section.
+  > Delete src/loom/streaming/_observability.py (StreamingObservabilityConfig)
+  > Delete src/loom/streaming/observability/ directory (old observer stack)
+  > Add observability: ObservabilityConfig field to BytewaxRuntimeConfig
+  > StreamingRunner.from_config() calls ObservabilityRuntime.from_config() directly
+  > StreamingTestRunner defaults to ObservabilityRuntime.noop(); callers pass
+  > observability_runtime= explicitly when needed
+  > Update tests to use new config shape and ObservabilityRuntime([observer])
+
+- **streaming:** replace KafkaStreamingObserver with LifecycleEvent/TRANSPORT<br>
+  > Eliminates the parallel KafkaStreamingObserver protocol hierarchy (NoopKafkaObserver,
+  > StructlogKafkaObserver) and models all Kafka transport events as LifecycleEvent with
+  > Scope.TRANSPORT. KafkaPrometheusMetrics now implements the LifecycleObserver protocol
+  > via a single on_event() dispatcher instead of four typed callback methods.
+
+- **streaming:** preserve trace lineage across boundaries
+
+### prometheus
+- **prometheus:** add KafkaMetricName enum and drop loom_ prefix<br>
+  > Extracts Prometheus metric names into a public KafkaMetricName StrEnum so
+  > callers can reference metric names without magic strings. Removes the loom_
+  > namespace prefix from all four Kafka instruments (produced_total,
+  > consumed_total, encode_duration_seconds, decode_duration_seconds).
+
+- **prometheus:** drop loom prefix from lifecycle metrics
+
+### rest
+- **rest:** use core observability runtime
+- **rest:** read prometheus from observability config
+
+### celery
+- **celery:** adopt async bridge and runtime config
+
+### etl
+- **etl:** make spark pytest plugin opt-in
+
+
+
+## ✅ Tests
+### kafka
+- **kafka:** update metric name assertions after loom_ prefix removal
+
+### observability
+- **observability:** cover lineage and runtime branches
+
+### integration
+- **integration:** add in-memory REST, observability, and bootstrap integration tests
+
+### etl
+- **etl:** cover prometheus flush on runner shutdown
+
+
+## 🛠 Chores
+### deps
+- **deps:** bump click to 8.3.3
+
+

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loom-kernel
-Version: 0.4.0
+Version: 0.6.0
 Summary: Loom Python project
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -54,6 +54,15 @@ Requires-Dist: uvicorn<1.0,>=0.30; extra == 'rest'
 Requires-Dist: uvloop<1.0,>=0.21; (sys_platform != 'win32') and extra == 'rest'
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy<3.0,>=2.0; extra == 'sqlalchemy'
+Provides-Extra: streaming
+Requires-Dist: anyio<5.0,>=4.0; extra == 'streaming'
+Requires-Dist: bytewax>=0.21; extra == 'streaming'
+Requires-Dist: confluent-kafka<3.0,>=2.6; extra == 'streaming'
+Requires-Dist: opentelemetry-api<2.0,>=1.27; extra == 'streaming'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.27; extra == 'streaming'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.27; extra == 'streaming'
+Requires-Dist: opentelemetry-sdk<2.0,>=1.27; extra == 'streaming'
+Requires-Dist: uvloop<1.0,>=0.21; (sys_platform != 'win32') and extra == 'streaming'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -387,8 +396,13 @@ app:
 database:
   url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
 
-metrics:
-  enabled: false
+observability:
+  log:
+    enabled: false
+  otel:
+    enabled: false
+  prometheus:
+    enabled: false
 ```
 
 ```python

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/README.md

@@ -329,8 +329,13 @@ app:
 database:
   url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
 
-metrics:
-  enabled: false
+observability:
+  log:
+    enabled: false
+  otel:
+    enabled: false
+  prometheus:
+    enabled: false
 ```
 
 ```python

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/conf.py

@@ -69,6 +69,8 @@ def _skip_duplicate_reexports(
         ("loom.core.errors", "RuleViolations"),
         ("loom.core.use_case", "RuleViolation"),
         ("loom.core.use_case", "RuleViolations"),
+        ("loom.etl.lineage", "ETLObservabilityConfig"),
+        ("loom.testing", "CompilationError"),
         ("loom.rest.model", "PaginationMode"),
     }
     if (current_module, name) in duplicated_reexports:

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/etl/pipelines.md

@@ -165,9 +165,15 @@ storage:
   tmp_root: /var/lib/loom/lake/_tmp
 
 observability:
-  log: true
-  slow_step_threshold_ms: 30000
-  run_sink:
+  log:
+    enabled: true
+  otel:
+    enabled: false
+  prometheus:
+    enabled: true
+    pushgateway_url: ${oc.env:PUSHGATEWAY_URL,http://127.0.0.1:9091}
+  lineage:
+    enabled: true
     # Choose exactly one destination:
     root: /var/lib/loom/lake/_runs
     # database: ops

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/etl/testing.md

@@ -42,7 +42,8 @@ def test_double_amount(loom_polars_runner):
     result.assert_count(2)
 ```
 
-Pytest fixtures auto-registered: `loom_polars_runner`, `loom_spark_runner`.
+Pytest fixtures: `loom_polars_runner`. Import `loom.etl.testing.spark` or
+register it explicitly in Spark-enabled suites to use `loom_spark_runner`.
 
 ## Spark integration tests
 

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/examples-repo/index.md

@@ -578,12 +578,15 @@ app:
 database:
   url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///./store.db}
 
-trace:
-  enabled: ${oc.decode:${oc.env:TRACE_ENABLED,true}}
-
-metrics:
-  enabled: ${oc.decode:${oc.env:METRICS_ENABLED,true}}
-  path: /metrics
+observability:
+  log:
+    enabled: true
+  otel:
+    enabled: false
+  prometheus:
+    enabled: ${oc.decode:${oc.env:METRICS_ENABLED,true}}
+    config:
+      path: /metrics
 ```
 
 ### Manifest mode (explicit registry)

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/getting-started/etl.md

@@ -90,9 +90,15 @@ storage:
   tmp_root: /var/lib/loom/lake/_tmp
 
 observability:
-  log: true
-  slow_step_threshold_ms: 30000
-  run_sink:
+  log:
+    enabled: true
+  otel:
+    enabled: false
+  prometheus:
+    enabled: true
+    pushgateway_url: ${oc.env:PUSHGATEWAY_URL,http://127.0.0.1:9091}
+  lineage:
+    enabled: true
     root: /var/lib/loom/lake/_runs
 ```
 

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/getting-started/rest.md

@@ -1,4 +1,4 @@
-# Quickstart
+# REST Quickstart
 
 `loom-kernel` lets you define business behavior in typed use cases and expose it
 through REST interfaces — with full auto-CRUD, background jobs, and Celery workers.
@@ -58,6 +58,12 @@ app:
 
 database:
   url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
+
+observability:
+  log:
+    enabled: false
+  otel:
+    enabled: false
 ```
 
 ```python
@@ -330,12 +336,15 @@ app:
 database:
   url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
 
-metrics:
-  enabled: true
-  path: /metrics
-
-trace:
-  enabled: true
+observability:
+  log:
+    enabled: true
+  otel:
+    enabled: false
+  prometheus:
+    enabled: true
+    config:
+      path: /metrics
 ```
 
 ```python

loom_kernel-0.6.0/docs/getting-started/streaming.md

@@ -0,0 +1,97 @@
+# Streaming Quickstart
+
+`loom.streaming` lets you declare typed streaming flows with explicit sources,
+steps, batching, branching, and transport wiring.
+
+The companion demo repository for this subsystem is
+[dummy-loom-streaming](https://github.com/the-reacher-data/dummy-loom-streaming).
+
+## Install
+
+Choose the streaming runtime and Kafka transport:
+
+```bash
+pip install "loom-kernel[streaming,kafka]"
+```
+
+## Minimal flow
+
+```python
+from loom.streaming import (
+    CollectBatch,
+    FromTopic,
+    IntoTopic,
+    Process,
+    StreamFlow,
+    WithAsync,
+    payload,
+)
+
+from app.streaming.tasks import FetchRequestTask
+from app.streaming.types import ScrapeRequest, ScrapeResponse
+
+
+async_scrape_flow = StreamFlow(
+    name="async_smoke_flow",
+    source=FromTopic[ScrapeRequest](
+        name="scrape.requests",
+        payload=ScrapeRequest,
+    ),
+    process=Process(
+        CollectBatch(max_records=50, timeout_ms=2000),
+        WithAsync(
+            process=Process(
+                FetchRequestTask,
+                IntoTopic[ScrapeResponse](
+                    name="scrape.responses",
+                    payload=ScrapeResponse,
+                ),
+            ),
+            max_concurrency=50,
+        ),
+    ),
+)
+```
+
+## Run it
+
+Use the Bytewax runner to compile the flow, resolve YAML bindings, and execute
+the graph:
+
+```python
+from loom.streaming.bytewax import StreamingRunner
+
+runner = StreamingRunner.from_yaml(async_scrape_flow, "config/streaming.yaml")
+runner.run()
+```
+
+## Public imports
+
+Prefer the public surface:
+
+```python
+from loom.streaming import (
+    Broadcast,
+    CollectBatch,
+    ContextFactory,
+    Fork,
+    FromTopic,
+    IntoTopic,
+    Message,
+    Process,
+    RecordStep,
+    Router,
+    StreamFlow,
+    With,
+    WithAsync,
+    msg,
+    payload,
+)
+```
+
+Use `loom.streaming.nodes`, `loom.streaming.kafka`, and
+`loom.streaming.bytewax` only when you need a narrower or runtime-specific
+surface.
+
+For a runnable end-to-end example, see the companion repository:
+[dummy-loom-streaming](https://github.com/the-reacher-data/dummy-loom-streaming).

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/guides/celery.md

@@ -282,6 +282,12 @@ celery:
 
   # For integration tests: run tasks synchronously in the calling process.
   task_always_eager: false
+
+  # Async bridge settings used by async jobs/callbacks.
+  runtime:
+    backend: asyncio          # asyncio or trio
+    use_uvloop: true          # only applies to asyncio on supported platforms
+    shutdown_timeout_ms: 10000
 ```
 
 (per-job-overrides-from-yaml)=
@@ -497,6 +503,9 @@ celery:
   broker_url: "redis://localhost:6379/15"
   result_backend: "redis://localhost:6379/15"
   task_always_eager: true
+  runtime:
+    backend: asyncio
+    use_uvloop: false
 ```
 
 Or patch it in a pytest fixture:

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/guides/etl.md

@@ -165,9 +165,15 @@ storage:
   tmp_root: /var/lib/loom/lake/_tmp
 
 observability:
-  log: true
-  slow_step_threshold_ms: 30000
-  run_sink:
+  log:
+    enabled: true
+  otel:
+    enabled: false
+  prometheus:
+    enabled: true
+    pushgateway_url: ${oc.env:PUSHGATEWAY_URL,http://127.0.0.1:9091}
+  lineage:
+    enabled: true
     # Choose exactly one destination:
     root: /var/lib/loom/lake/_runs
     # database: ops

loom_kernel-0.6.0/docs/guides/quickstart.md

@@ -0,0 +1,7 @@
+# REST Quickstart
+
+The canonical REST quickstart lives in
+[getting-started/rest](../getting-started/rest.md).
+
+Use the REST quickstart for model-driven APIs, auto-CRUD, use cases, jobs, and
+FastAPI delivery.

{loom_kernel-0.4.0 → loom_kernel-0.6.0}/docs/index.rst

@@ -42,12 +42,19 @@ Official hosted documentation:
 Companion demo application:
 `dummy-loom <https://github.com/the-reacher-data/dummy-loom>`_.
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Overview
+
+   overview
+
 .. toctree::
    :maxdepth: 2
    :caption: Getting Started
 
    getting-started/rest
    getting-started/etl
+   getting-started/streaming
 
 .. toctree::
    :maxdepth: 2
@@ -67,6 +74,12 @@ Companion demo application:
    etl/testing
    etl/examples
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Streaming
+
+   streaming/bytewax
+
 .. toctree::
    :maxdepth: 2
    :caption: Reference