doccmd

2026.3.26.2 · active · verified Thu Apr 16

doccmd is a command-line tool (CLI) designed to run external commands, such as linters and formatters, against code blocks embedded within reStructuredText and Markdown documentation files. It helps ensure the code examples in documentation remain correct and up-to-date. The library follows a rapid release cadence, with frequent updates, often on a daily basis.

Common errors

```
NameError: name 'my_function' is not defined (or similar error within grouped code blocks)
```
cause By default, `doccmd` processes each code block independently. If you have multiple related code blocks that should be treated as a single unit (e.g., one defining a function and a later one calling it), they will error if not explicitly grouped.

fix Group related code blocks using `` and `` comments around them in Markdown, or `.. group-doccmd[all]: start` and `.. group-doccmd[all]: end` directives in reStructuredText.
```
doccmd: error: changes to grouped code blocks will not be written back
```
cause A tool run by `doccmd` attempted to modify the content of a code block that is part of a 'group'. By design, `doccmd` prevents tools from modifying grouped code blocks and errors out to prevent silent data loss or unexpected behavior.

fix If you accept that changes to grouped blocks will not be written back to the documentation, rerun `doccmd` with the `--no-fail-on-group-write` option. Otherwise, refactor your documentation or tools to avoid modifying grouped blocks, or do not group blocks that need to be modified by tools.

Warnings

gotcha doccmd creates temporary files for each code block (e.g., `doccmd_*.py`). These files can interfere with linters or other tools if not explicitly ignored in their configurations.
Fix: Configure your linter (e.g., Ruff) to ignore files matching `doccmd_*.py` or the prefix specified by `--temporary-file-name-prefix` in its configuration (e.g., `[tool.ruff] lint.per-file-ignores."doccmd_*.py" = ["S105"]`).
breaking When grouping code blocks (using `group doccmd[all]: start`/`end`), tools which modify the code block content will not write changes back to the original documentation file for grouped blocks. By default, this will cause `doccmd` to error.
Fix: To prevent `doccmd` from erroring in this scenario, use the `--no-fail-on-group-write` option. Be aware that the documentation will not be updated with the changes from tools for grouped blocks.
gotcha The library has a very rapid release cadence with frequent updates, sometimes daily. While this means quick bug fixes and new features, it may also introduce minor behavioral changes or regressions between closely spaced versions.
Fix: Pin your `doccmd` version in production environments to avoid unexpected behavior from frequent updates, e.g., `pip install doccmd==2026.3.26.2`.

Install

pip install doccmd Install latest version

Quickstart

This quickstart demonstrates how to use `doccmd` from the command line to execute code blocks in a Markdown file. `doccmd` will find the code blocks, create temporary files, run them, and report any errors. By default, it runs all supported languages. You can specify a language with `--language`.

# Create a sample markdown file
cat << EOF > example.md
# My Project

This is an example document.

```python
import os
print("Hello from Python!")
```

```shell
echo "Hello from Shell!"
```
EOF

# Run doccmd to execute Python and shell code blocks
doccmd example.md

view raw JSON →