Executable Documentation

Copy Markdown View Source

Livebook notebooks are a form of executable documentation - documentation that can be verified by running it.

What is Executable Documentation?

Traditional documentation (README, wiki, blog posts) contains code snippets that are copied and pasted by readers. There's no guarantee the code still works.

Executable documentation is different: the code is run automatically, ensuring it always works.

Livebook as Executable Documentation

Livebook's .livemd format is perfect for executable documentation because:

  1. Readable as plain text - it's Markdown
  2. Version controllable - diff-friendly text format
  3. Runnable - Livebook can execute it directly
  4. Testable - livebook_test can verify it in CI

The livebook_test Approach

livebook_test treats notebooks as test artifacts:

  1. Discover - Find all .livemd files in your project
  2. Export - Convert them to standalone Elixir scripts
  3. Run - Execute each script and check for errors
  4. Report - Summarize which notebooks pass and fail

This creates a feedback loop: documentation that breaks is caught immediately.

Best Practices

Keep Notebooks Simple

Notebooks used as executable documentation should:

  • Avoid long-running computations
  • Avoid external service dependencies (or mock them)
  • Use deterministic outputs
  • Keep Mix.install dependencies minimal

Structure for Testability

# My Feature Guide

## Setup

```elixir
Mix.install([{:my_lib, "~> 0.5"}])
```

## Basic Usage

```elixir
MyLib.hello("world") |> IO.puts()
```

## Advanced Usage

```elixir
MyLib.configure(option: :value)
```

Separate Interactive from Testable

Some Livebook features (inputs, smart cells, Kino widgets) are interactive and won't work in a headless test. Keep interactive elements in dedicated "demo" notebooks, separate from the "testable" documentation notebooks.

Including Notebooks in ExDoc

Livebook .livemd files can be included in ExDoc's extras independently of livebook_test. Add them to mix.exs:

docs: [
  extras: [
    "README.md",
    "examples/basic.livemd"
  ]
]

ExDoc will render the .livemd files as formatted documentation pages.

Next Steps