Skip to content

Executable Code in Documentation

This guide explains how meteaudata's documentation supports executable code blocks that run at build time and inject live outputs directly into the documentation.

Overview

The meteaudata documentation uses the markdown-exec plugin to:

  • Run actual Python code during documentation build
  • Capture real outputs including print statements, plots, and data
  • Fail the build if code examples have errors (ensuring docs stay up-to-date)
  • Maintain context across multiple code blocks using sessions
  • Show both code and output for realistic examples

Basic Usage

Standard Code Blocks vs Executable Blocks

Standard code block (static): 

# This code is just displayed, not executed
signal = Signal(data, "Temperature", provenance, "°C")
print(f"Created signal: {signal.name}")

Executable code block: 

Created series with 5 values
Mean: 22.0

The exec="1" result="console" option (or exec="true", exec="on") tells markdown-exec to execute the code block.

Using Sessions for State Persistence

Sessions allow you to share variables between code blocks:

Created signal: Temperature#1
Time series: ['Temperature#1_RAW#1']

After resampling: ['Temperature#1_RAW#1', 'Temperature#1_RESAMPLED#1']

Output Display Options

Show Code Above Output (default)

print("This is the output")
print("Code appears above this")

This is the output
Code appears above this

Show Code Below Output

This is the output
Code appears below this

print("This is the output")
print("Code appears below this")

Tabbed Display (Material theme)

print("Code and output in tabs")
print("Code tab on the left")

Code and output in tabs
Code tab on the left

Error Handling

When code fails, markdown-exec will: 1. Show the error in the rendered documentation 2. Log a warning during build with the full traceback 3. Display the error inline so readers can see what went wrong

The id option helps identify which code block failed in build logs:

# Use id to identify problematic blocks in your markdown files
​```python exec="1" result="console" id="my-example"
# Your code here
​```

Best Practices

Writing Executable Examples

DO:

  • Use sessions to build up complex examples step-by-step
  • Include meaningful print statements to show outputs
  • Test examples work before committing
  • Use id option for easier debugging

DON'T:

  • Rely on external files or network resources
  • Use overly complex examples that obscure the main point
  • Forget to specify session names when continuing contexts
  • Mix unrelated concepts in single code blocks

Session Organization

For documentation pages with multiple examples:

  1. Use unique session names for each independent example
  2. Reuse session names when continuing the same example
  3. Don't share sessions across pages (each page starts fresh)

Example:

Example 1: x = 10

Still example 1: x = 10

Example 2: y = 20

Integration with MkDocs

The markdown-exec plugin:

  1. Runs during mkdocs build or mkdocs serve
  2. Works with Material theme for tabbed display
  3. Integrates with other plugins like mkdocstrings
  4. Provides build-time validation of code examples

Migration from Bespoke System

Our previous system used custom scripts with exec="context_name" syntax. The new system uses:

  • exec="1" result="console" instead of exec="simple_signal"
  • session="name" instead of exec="continue"
  • No need for _template.md files - edit markdown files directly
  • Cleaner integration with standard MkDocs workflow

Advanced Features

Setting Working Directory

Current directory: /home/runner/work/meteaudata/meteaudata/src

HTML Output

This is HTML output

Useful for rich displays

Custom Result Formatting

{"key": "value", "number": 42}

Reference

For complete documentation of markdown-exec features, see: - markdown-exec documentation - GitHub repository