doccmd

What it is and what it does

doccmd is a command-line tool that extracts code blocks from documentation files and runs external commands (linters, formatters, type checkers) against them. It works with reStructuredText, Markdown, MyST, MDX, Djot, and Norg files, automatically handling language detection and code block extraction so you can validate that the code examples in your documentation actually work and conform to your project's standards.

The tool preserves line numbers in error output by padding code blocks before execution, and can strip Python REPL prompts (>>>) when processing interactive console examples. It's designed to integrate into CI/CD pipelines and pre-commit hooks, letting you catch broken or outdated code examples before they reach users. Dependencies include click for CLI scaffolding, beartype for runtime type validation, and dulwich for version control operations.

Use it for:

• Validate that Python code examples in your README actually pass type checking with mypy or ruff.
• Ensure shell script snippets in documentation pass linting tools like shellcheck before release.
• Run formatters (ruff format, gofmt) on code blocks to keep examples style-consistent with your codebase.
• Test interactive Python sessions (pycon blocks) by stripping prompts, running linters, and restoring them.
• Integrate into pre-commit hooks to catch broken documentation examples on every commit.
• Verify code blocks across multiple documentation formats (Sphinx, MyST, plain Markdown) in a single pass.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Runs linters, formatters, and other command-line tools against code blocks embedded in documentation files (reStructuredText, Markdown, MyST, MDX, Djot, Norg).

Yes. The package is actively maintained, has no known vulnerabilities, uses a permissive MIT license, and solves a real problem—keeping documentation code examples in sync with your actual codebase standards. Low install friction and broad format support make it a practical choice for projects that care about documentation quality. Install it if you maintain documentation with embedded code examples and want automated validation.

Install

doccmd on PyPI

pip install doccmd

uv add doccmd

poetry add doccmd

Installing doccmd

Before you install

Low friction: pure Python wheel with 9 runtime dependencies including click for CLI, beartype for type checking, and dulwich for version control integration. Active maintenance with a release 26 days ago; repository has 28 stars and recent commits.

License in practice

MIT license (permissive): you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

$ pip install doccmd
$ doccmd --language=python --command="mypy" README.md
$ doccmd --language=shell --command="shellcheck --shell=bash" docs/

Requires Python 3.11 or later; the command-line tool being invoked (e.g., mypy, shellcheck) must be installed separately and available in PATH.

Verify before relying

• Whether the tool handles nested or indented code blocks correctly across all supported formats.
• Performance characteristics when processing large documentation files with many code blocks.
• Compatibility with custom or non-standard code block syntax extensions.

Package facts

Evidence: doccmd-2026.7.19-py3-none-any.whl

Keywords: markdown, rst, sphinx, testing

Tags

More Documentation packages