validoc
Documentation Execution and Testing Tool
validoc is an executable documentation testing tool that makes markdown documentation tutorials runnable as tests. It parses markdown files with annotated code blocks and executes them, verifying outputs. The tutorial is the test - single source of truth.
Problem
Documentation tutorials suffer from documentation rot: they become outdated as software evolves, but there's no automated way to detect this. Users follow broken tutorials and blame themselves.
Solution
Annotate markdown code blocks to make them executable:
```bash exec
echo "Hello, World!"
```
```output contains
Hello
```
Run the tutorial as a test:
validoc run docs/tutorials/getting-started.md
Installation
# Install with uv
uv add validoc
# Or install with pip
pip install validoc
For development:
git clone https://github.com/abilian/validoc.git
cd validoc
uv sync --all-extras
Quick Start
# Run a tutorial
validoc run examples/01-hello-world.md
# Run with verbose output
validoc run examples/01-hello-world.md -v
# Keep files for debugging
validoc run tutorial.md --workdir /tmp/test --no-teardown
# Validate without executing
validoc check tutorial.md
# List executable blocks
validoc list tutorial.md
Features
- Readable first - Documentation remain beautiful, human-readable markdown
- Standard markdown - Works with GitHub, MkDocs, VS Code without modification
- Multiple block types - Execute commands, create files, verify output, assert conditions
- Sandbox execution - Runs in temporary directory, cleans up after
- Debug-friendly -
--no-teardownpreserves files for inspection
Block Types
| Type | Syntax | Purpose |
|---|---|---|
| Execute | ```bash exec |
Run shell commands |
| File | ```file path=config.yml |
Create files |
| Output | ```output contains |
Verify command output |
| Assert | ```assert file-exists path=app.py |
Check conditions |
Execute Block Attributes
| Attribute | Description |
|---|---|
id=name |
Unique identifier |
dir=path |
Working directory |
timeout=60 |
Timeout in seconds |
expect=1 |
Expected exit code |
skip |
Skip this block |
continue-on-error |
Don't stop on failure |
Output Matching Modes
| Mode | Description |
|---|---|
output contains |
Text appears in output (default) |
output exact |
Exact match |
output regex |
Regular expression |
Tutorial Configuration
Use YAML frontmatter for configuration:
---
tutorial:
name: my-tutorial
env:
DEBUG: "true"
setup:
- echo "Setting up..."
teardown:
- rm -rf myapp || true
---
Examples
The examples/ directory contains tutorials demonstrating all features:
01-hello-world.md- Minimal example02-file-creation.md- Creating files03-output-matching.md- Output verification modes04-assertions.md- Assertion types05-frontmatter.md- YAML configuration
Run all examples:
uv run pytest tests/c_examples -v
Documentation
| Document | Description |
|---|---|
| docs/tutorial.md | Comprehensive user guide |
| notes/specs.md | Complete specification |
| notes/design.md | Architecture and design |
| notes/plans.md | Future plans |
Development
# Install with dev dependencies
uv sync --all-extras
# Run all tests (98 tests)
uv run pytest
# Run specific test categories
uv run pytest tests/a_unit # Unit tests
uv run pytest tests/b_integration # Integration tests
uv run pytest tests/c_examples # Example tests
# Linting
uv run ruff check src tests
Package Structure
src/validoc/
├── cli.py # Command-line interface
├── parser.py # Markdown parser
├── executor.py # Block execution
├── runner.py # Orchestration
├── reporter.py # Console output
├── models.py # Data structures
└── constants.py # Enums
License
Apache-2.0
Metadata
Release files for validoc 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| validoc-0.2.0.tar.gz | 16.0 kB | Without provenance | Details for validoc-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| validoc-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for validoc-0.2.0-py3-none-any.whl |
Total release size: 37.4 kB
Release files / validoc-0.2.0.tar.gz
| Download URL | validoc-0.2.0.tar.gz |
|---|---|
| Size | 16.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8dbc85c3e00fdf2059bfa8c6ab904e6a4c40739a31ac9cae083e0248c555c91c
|
|
BLAKE2b-256 checksum How to use checksums |
3f993f1729c5045202347ab32e36ebd722bba4e228345dc3ccb6f76346214bc8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / validoc-0.2.0-py3-none-any.whl
| Download URL | validoc-0.2.0-py3-none-any.whl |
|---|---|
| Size | 21.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a4d92f8bcd2e9952e7a116d04e391c409f2d4daff8873d149d47e447da0cc43
|
|
BLAKE2b-256 checksum How to use checksums |
7a57b9130bc1e5a207c8d17572e1d569aa14cc937e13cf2a2a5e204b12c4dd1c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for validoc 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.