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

A Sphinx extension that executes arbitrary shell commands and embeds their output directly into reStructuredText documentation, with options for syntax highlighting, text replacement, and prompt display.

Yes, if you maintain Sphinx documentation and want to keep command output examples in sync with reality. The low install friction and permissive license make it a safe addition. However, the aging codebase (last release 2018) means you should verify compatibility with your Python version and Sphinx version before relying on it for critical docs. No known security vulnerabilities.

Install

sphinxcontrib-runcmd on PyPI

pip install sphinxcontrib-runcmd

uv add sphinxcontrib-runcmd

poetry add sphinxcontrib-runcmd

Installing sphinxcontrib-runcmd

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.

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:

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

Verify before relying

• Whether the package works reliably with modern Python versions beyond 3.6, given the last release was 2018.
• Whether command execution works across Windows, macOS, and Linux without platform-specific issues.
• Performance characteristics when executing many commands or long-running processes in a single build.

Package facts

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

Tags

More Utilities packages