Skip to content

Commit 2d147d9

Browse files
committed
docs(readme): add the notebook tutorial overview
1 parent 44bf18b commit 2d147d9

1 file changed

Lines changed: 22 additions & 1 deletion

File tree

README.md

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,30 @@ Documentation extraction for Elixir, without a renderer attached.
1010
[Installation](#installation) |
1111
[Quick start](#quick-start) |
1212
[Configuration](#configuration) |
13+
[Try it interactively](#try-it-interactively) |
1314
[Artifacts](#what-comes-out) |
1415
[Serving](#serving-it)
1516

1617
---
1718

19+
## Try It Interactively
20+
21+
The Livebook notebooks are executable tutorials, not extra API reference pages.
22+
Start with the build-pipeline notebook in a browser:
23+
24+
[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffuthr%2Fdoc_shell%2Fmain%2Fnotebooks%2Fbuild-pipeline.livemd)
25+
26+
- **[The Build Pipeline](https://livebook.dev/run?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffuthr%2Fdoc_shell%2Fmain%2Fnotebooks%2Fbuild-pipeline.livemd)** -
27+
Follow one build from source files to generated artifacts.
28+
- **[Artifact Contract](https://livebook.dev/run?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffuthr%2Fdoc_shell%2Fmain%2Fnotebooks%2Fartifact-contract.livemd)** -
29+
Inspect the public JSON shapes, envelopes, manifests, and presentation indexes.
30+
- **[OpenAPI Adapters](https://livebook.dev/run?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffuthr%2Fdoc_shell%2Fmain%2Fnotebooks%2Fopenapi-adapters.livemd)** -
31+
Work through the default document, shipped adapters, custom adapters, and validation errors.
32+
- **[Serving Artifacts](https://livebook.dev/run?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffuthr%2Fdoc_shell%2Fmain%2Fnotebooks%2Fserving-artifacts.livemd)** -
33+
Walk through static serving, runtime caching, reloads, gates, and controller usage.
34+
35+
---
36+
1837
## Why
1938

2039
Most documentation tooling couples extraction to rendering. The thing that
@@ -141,7 +160,9 @@ For a guided walkthrough, start with
141160
[artifact contract notebook](notebooks/artifact-contract.livemd) documents every
142161
file DocShell writes, and the
143162
[OpenAPI adapters notebook](notebooks/openapi-adapters.livemd) covers adapter
144-
selection and implementation.
163+
selection and implementation. Use the
164+
[serving artifacts notebook](notebooks/serving-artifacts.livemd) when wiring the
165+
runtime cache, Plug, or a host controller.
145166

146167
## What comes out
147168

0 commit comments

Comments
 (0)