sphinxcontrib-runcmd

What it is and what it does

sphinxcontrib-runcmd is a Sphinx extension that lets you run shell commands during documentation builds and automatically insert their output into your reStructuredText files. Instead of manually copying command output into your docs, you write a directive with the command you want to run, and the extension executes it and captures the result. It builds on Sphinx's standard code-block directive, so you get all the usual formatting options like line numbers, syntax highlighting, and line ranges.

The extension adds several options beyond code-block: you can specify output syntax highlighting separately from the command, display the command prompt itself, dedent output, and apply regex-based text replacements to clean up or anonymize the output. This makes it useful for keeping documentation in sync with actual tool behavior without manual updates.

Use it for

• Documenting CLI tools by running them with --help and embedding the actual output in your docs.
• Keeping API documentation examples current by executing test scripts and showing their real output.
• Building tutorials where command results need to stay synchronized with the actual tool behavior.
• Generating reference documentation that includes real command output without manual copying.
• Creating reproducible documentation where the build process verifies that examples actually work.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

sphinxcontrib-runcmd on PyPI

Before you install

Installation is straightforward with a single dependency on sphinx and a pure-Python wheel. The package is aging—last release was 2018-11-08 and no updates since—but the repository remains active with a recent commit on 2025-04-28, suggesting maintenance rather than abandonment.

Requires Sphinx to be installed and a working Sphinx documentation project.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute it freely with minimal restrictions.

Quickstart

pip install sphinxcontrib-runcmd

In conf.py:
extensions = ["sphinxcontrib.runcmd"]

In your .rst file:
.. runcmd:: python script.py -h
   :syntax: bash
   :prompt:

Package facts

Evidence: sphinxcontrib_runcmd-0.2.0-py2.py3-none-any.whl

Tags

More Utilities packages

See also sphinx-prompt · sphinxcontrib-programoutput · sphinx_mdinclude · sphinx-jinja · sphinx-substitution-extensions · sphinx-panels · changelog · sphinxcontrib-typer · sphinxcontrib-video · rich-rst