docsmoke 1.0.0

Executable documentation smoke tests for Markdown snippets.

docsmoke

docsmoke validates executable Markdown snippets before they drift out of sync with the software they document.

It is built for maintainers who want docs to fail like code: run the fenced shell and Python examples in README.md and docs/, assert on expected output, and fail CI when installation guides or CLI examples stop working.

Highlights

• Markdown-native snippet discovery with explicit docsmoke opt-in markers
• Built-in shell and Python executors
• Per-snippet directives for timeouts, expectations, environment variables, working directories, and skips
• CLI, JSON, and Markdown reporting
• GitHub Action for CI usage
• Typed Python package with strict linting, mypy, pytest, pre-commit, Docker, and release automation

Quick start

python3.11 -m pip install docsmoke
docsmoke --help

Mark runnable snippets in Markdown:

```bash docsmoke
# docsmoke: name=quickstart; expect-contains=passed
docsmoke scan README.md --quiet
```

Run a scan:

# docsmoke: expect-contains=list-snippets
docsmoke --help

List what would run:

# docsmoke: expect-contains=example-snippet
docsmoke list-snippets examples --json

Directive syntax

Directives live in the first lines of a runnable fenced block:

```bash docsmoke
# docsmoke: name=install-check
# docsmoke: cwd=examples
# docsmoke: expect-contains=hello
printf 'hello\n'
```

Supported directives:

• name=<value>: human-friendly snippet label
• cwd=<path>: working directory relative to the project root
• timeout=<seconds>: positive per-snippet timeout
• expect-contains=<text>: required stdout or stderr substring
• expect-regex=<pattern>: required regex match against stdout or stderr
• env.NAME=<value>: environment variable override
• shell=<binary>: shell override for shell snippets
• skip[=true|false]: skip the snippet without removing it

GitHub Action

Use the moving @v1 tag to receive compatible 1.x fixes automatically, or pin an exact release such as @v1.0.0 for fully reproducible workflow inputs.

- uses: dev-ugurkontel/docsmoke@v1
  with:
    paths: README.md docs examples

Documentation

• docs/INSTALL.md: installation options
• docs/USAGE.md: CLI usage and workflows
• docs/CONFIG.md: configuration file reference
• docs/ARCHITECTURE.md: internal architecture
• docs/RELEASE.md: release and tag-management process
• docs/REPOSITORY.md: repository settings checklist
• CONTRIBUTING.md: contribution workflow
• SECURITY.md: private vulnerability disclosure
• SUPPORT.md: usage help and issue routing

Development

make all

License

Apache 2.0 licensed. See LICENSE.