Run Documentation Examples

Extracts Python code blocks from markdown files and runs each example. LLM examples (llmPrompt, LLMPrompt, etc.) run as-is—they make real API calls when Ollama/OpenAI/Anthropic are configured.

When to Use

• After editing documentation
• Validating that doc examples execute correctly
• CI-style doc checks

Environment

Use .venv. Run via .venv/bin/python or activate with source .venv/bin/activate.

Workflow

Recommended (pytest): Run from the project root:

pytest tests/test_doc_examples.py -v

Alternative (CLI):

run_doc_examples

Or via the skill script:

.venv/bin/python .cursor/skills/run-documentation-examples/scripts/run_documentation_examples.py

When running via the agent: Request full_network permissions so the sandbox allows connections to localhost (Ollama) and external APIs (OpenAI, Anthropic).

The pytest approach gives standard test output; run-doc-examples extracts examples, generates extracted_examples.py, and runs it (supports resume via .extracted_examples_fail_index).

Manual Two-Step Workflow

.venv/bin/python scripts/extract_documentation_examples.py
.venv/bin/python extracted_examples.py

CI Without Ollama

To skip doc examples when Ollama is unavailable: pytest tests/ -m "not requires_ollama"

Prerequisites for LLM Examples

• Ollama: ollama serve running; ollama pull llama3.2 (and mxbai-embed-large for embedding examples)
• OpenAI: TALKPIPE_openai_api_key or config
• Anthropic: Similar env/config
• Extras: pip install talkpipe[ollama] (or [openai], [anthropic], [all])

Failure Handling

The runner exits on first failure and writes .extracted_examples_fail_index with the failed example index. Run again to retry from that point. Delete the file to start from the beginning.