doccmd

library2026.3.26.2pypypiunverified

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.

testing devops

pip install doccmd

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · DOCCMD

doccmd

testingpythonv2026.3.26.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

doccmd --version

Debug

Known issues

gotchadoccmd 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"]`).

affects: All versions

breakingWhen 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.

affects: All versions supporting code block grouping

gotchaThe 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`.

affects: All recent versions (2025.x.x onwards)

Errors

Common errors & fixes

NameError: name 'my_function' is not defined (or similar error within grouped code blocks)

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 `<!-- group doccmd[all]: start -->` and `<!-- group doccmd[all]: end -->` 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

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.

Upgrade

Version history

2026.3.26.2latest on PyPI · released Mar 26, 2026

Audit

Dependencies

markdown-it-py[plugins]requiredRequired for parsing Markdown files.

pygmentsrequiredUsed for syntax highlighting and general code processing.

docutilsrequiredRequired for parsing reStructuredText files.

tomlrequiredLikely used for configuration file parsing (e.g., pyproject.toml).

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/adamtheturtle/doccmd ↗

packagehttps://pypi.org/project/doccmd/ ↗

homepagehttps://pypi.org/project/doccmd ↗

docshttps://adamtheturtle.github.io/doccmd/ ↗