{"id":8125,"library":"doccmd","title":"doccmd","description":"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.","status":"active","version":"2026.3.26.2","language":"en","source_language":"en","source_url":"https://github.com/adamtheturtle/doccmd","tags":["documentation","testing","CLI","markdown","restructuredtext","linter","formatter"],"install":[{"cmd":"pip install doccmd","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for parsing Markdown files.","package":"markdown-it-py[plugins]","optional":false},{"reason":"Used for syntax highlighting and general code processing.","package":"pygments","optional":false},{"reason":"Required for parsing reStructuredText files.","package":"docutils","optional":false},{"reason":"Likely used for configuration file parsing (e.g., pyproject.toml).","package":"toml","optional":false}],"imports":[],"quickstart":{"code":"# Create a sample markdown file\ncat << EOF > example.md\n# My Project\n\nThis is an example document.\n\n```python\nimport os\nprint(\"Hello from Python!\")\n```\n\n```shell\necho \"Hello from Shell!\"\n```\nEOF\n\n# Run doccmd to execute Python and shell code blocks\ndoccmd example.md\n","lang":"bash","description":"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`."},"warnings":[{"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]\nlint.per-file-ignores.\"doccmd_*.py\" = [\"S105\"]`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions supporting code block grouping"},{"fix":"Pin your `doccmd` version in production environments to avoid unexpected behavior from frequent updates, e.g., `pip install doccmd==2026.3.26.2`.","message":"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.","severity":"gotcha","affected_versions":"All recent versions (2025.x.x onwards)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"NameError: name 'my_function' is not defined (or similar error within grouped code blocks)"},{"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.","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.","error":"doccmd: error: changes to grouped code blocks will not be written back"}]}