sphinxcontrib-runcmd

0.2.0 verified Fri May 01 auth: no python

A Sphinx extension that allows running shell commands and including their output in documentation. Version 0.2.0 (latest), stable release. No breaking changes reported.

pip install sphinxcontrib-runcmd

Common errors

error WARNING: unknown directive type 'runcmd' ↓

cause Extension not loaded or misspelled directive name.

fix

Ensure 'sphinxcontrib.runcmd' is in extensions list in conf.py and use '.. runcmd::' directive.

error OSError: [Errno 8] Exec format error ↓

cause Command string not found or no shebang without :shell: option.

fix

Add :shell: option or ensure command is a valid executable.

Warnings

gotcha The runcmd directive does not capture stderr by default; only stdout is included in the output. ↓

fix Use :stderr: flag to include stderr output.

gotcha Commands are executed within the Sphinx build environment; path and environment variables may differ from your shell. ↓

fix Use absolute paths or set environment via :env: option.

Imports

runcmd
```
from sphinxcontrib.runcmd import runcmd
```
Correct import path

Quickstart

Add the extension to your Sphinx project and use the runcmd directive.

import sphinxcontrib.runcmd

# In conf.py:
extensions = ['sphinxcontrib.runcmd']

# Then in your .rst files:
# .. runcmd:: echo 'Hello World'
#    :shell:
#    :workdir: /tmp