doccmd
Run commands against code blocks in reStructuredText and Markdown files.
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.11 or later; the command-line tool being invoked (e.g., mypy, shellcheck) must be installed separately and available in PATH.
- 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 · maintenance · safety
MIT (permissive) — MIT license (permissive): you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.
last release 2026-07-19 (26 days) · last repo commit 2026-08-14 · 28 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 175,991 downloads/mo, #10,255 on PyPI
Alternatives
Verify before relying
$ pip install doccmd
$ doccmd --language=python --command="mypy" README.md
$ doccmd --language=shell --command="shellcheck --shell=bash" docs/- 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.
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 on it.
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
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.
Requires Python 3.11 or later; the command-line tool being invoked (e.g., mypy, shellcheck) must be installed separately and available in PATH.
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/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
| License | MIT permissive |
| Python support | Supports the current Python release >=3.11 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 9 packagesbeartypecharset-normalizerclickclick-composecloupdulwichpygmentssybilsybil-extras |
| Maintenance | Actively maintained 26 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 175,991 / month, #10,255 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableEnvironment :: Web EnvironmentOperating System :: Microsoft :: WindowsOperating System :: POSIXProgramming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14 |
Evidence: doccmd-2026.7.19-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “lint code blocks in documentation”
- doccmdRuns linters, formatters, and other command-line tools against code…
- sphinxcontrib-shellcheckA Sphinx extension that automatically lints shell code blocks in…
- pytest-examplesA pytest plugin that finds, lints, runs, and validates Python code…
Give your agent the search over MCP, or paste the wish link into any chat.
More Documentation packages
Docutils converts plaintext documentation in reStructuredText format into multiple output formats including HTML, XML, and LaTeX using a modular processing system.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
Griffe extracts the complete structure and signatures of Python programs to generate API documentation or detect breaking changes in your project's public API.
Install it if you need to programmatically inspect Python code structure, generate API docs, or enforce API stability in CI.
A Sphinx extension that outputs documentation in serialized HTML formats (JSON and pickle) alongside standard HTML.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
A Sphinx extension that generates HTML help files from reStructuredText documentation source.
See also blacken-docs · sphinx-lint · rumdl · pytest-markdown-docs · markdown-exec · mdformat-ruff · rstcheck · pytest-examples · myst-parser · sphinx_mdinclude