{"id":8676,"library":"sphinxcontrib-programoutput","title":"Sphinx Program Output Extension","description":"sphinxcontrib-programoutput is a Sphinx extension that enables the literal insertion of arbitrary command output into documentation. This helps maintain up-to-date command examples. The current version is 0.19, with releases occurring on an irregular but active cadence, most recently in February 2026.","status":"active","version":"0.19","language":"en","source_language":"en","source_url":"https://github.com/OpenNTI/sphinxcontrib-programoutput/","tags":["Sphinx","documentation","CLI","output capture","reStructuredText"],"install":[{"cmd":"pip install sphinxcontrib-programoutput","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for Sphinx documentation builds; version 0.18+ requires Sphinx >= 5.0.","package":"Sphinx","optional":false},{"reason":"Requires Python >= 3.8 since version 0.18.","package":"Python","optional":false},{"reason":"Requires docutils >= 0.18.1 since version 0.18.","package":"docutils","optional":false},{"reason":"Required for interpreting ANSI color sequences in program output (only available on Python 3.10+).","package":"sphinxcontrib-ansi","optional":true}],"imports":[{"note":"This is a Sphinx extension, not a regular Python module to be imported directly into a Python script. It's enabled by adding its name to the 'extensions' list in Sphinx's conf.py configuration file.","wrong":"import sphinxcontrib.programoutput","symbol":"sphinxcontrib.programoutput","correct":"extensions = ['sphinxcontrib.programoutput'] # in conf.py"}],"quickstart":{"code":"# conf.py\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.programoutput'\n]\n\n# Your_Document.rst\n\n.. program-output:: python -V\n   :shell:\n\n.. command-output:: python -c \"print('Hello from Python!')\"\n\n# Example with options\n.. program-output:: git log -1\n   :cwd: .\n   :ellipsis: 2,-1\n","lang":"python","description":"After installation, enable the extension by adding 'sphinxcontrib.programoutput' to the `extensions` list in your Sphinx `conf.py`. Then, use the `.. program-output::` or `.. command-output::` reStructuredText directives in your documentation files to include command output. `command-output` mimics a shell session, including the command itself. Options like `cwd` (current working directory), `ellipsis` (to shorten output), `nostderr` (to hide stderr), `shell` (to pass command to system shell), and `returncode` (to expect specific exit codes) are available."},"warnings":[{"fix":"Upgrade Python to 3.8+ and Sphinx to 5.0+ (and docutils to 0.18.1+), or pin `sphinxcontrib-programoutput` to a version prior to 0.18 (e.g., `sphinxcontrib-programoutput<0.18`).","message":"Version 0.18 significantly updated its Python and Sphinx requirements. It dropped support for Python versions older than 3.8 and now effectively requires Sphinx 5.0+ and docutils 0.18.1+. Projects on older Python or Sphinx versions will need to upgrade or stick to programoutput < 0.18.","severity":"breaking","affected_versions":"0.18 and later"},{"fix":"Add `'sphinxcontrib.ansi'` to your `extensions` list in `conf.py`, set `programoutput_use_ansi = True`, and ensure your Python environment is 3.10+ if using this feature. Install `sphinxcontrib-ansi` if not already present.","message":"By default, `sphinxcontrib-programoutput` does not interpret ANSI escape codes for coloring. To enable this, you must explicitly enable the `sphinxcontrib.ansi` extension, ensure you are on Python 3.10+, and set the `programoutput_use_ansi` configuration value to `True`.","severity":"gotcha","affected_versions":"0.19 and later (for reintroduction of feature), all versions (for behavior without `sphinxcontrib.ansi`)"},{"fix":"Carefully specify `cwd` paths. For reliability, consider using absolute paths relative to the Sphinx project root (e.g., via `os.path.join(self.env.srcdir, 'my_relative_path')` if in a custom builder, or just absolute paths if the environment allows for it).","message":"Commands are executed in the top-level source directory by default. When using the `cwd` option, a relative path is interpreted relative to the *current source file*, while an absolute path is relative to the *root of the source directory*. Misunderstanding this can lead to 'file not found' errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For commands expected to fail with a specific exit code, add `:returncode: N` (where N is the expected code) to the directive. For example, `.. program-output:: my_failing_command :returncode: 1`.","message":"If a command returns a non-zero exit code, `sphinxcontrib-programoutput` by default emits a build warning. If you intend a command to fail (e.g., demonstrating error handling), this warning can be suppressed or inverted using the `:returncode:` option.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Edit your `conf.py` file and add `'sphinxcontrib.programoutput'` to the `extensions` list: `extensions = ['sphinxcontrib.programoutput', ...]`. Make sure there are no typos.","cause":"The `sphinxcontrib-programoutput` extension has not been correctly added to the `extensions` list in your Sphinx `conf.py` file. Sphinx cannot find or recognize the directive.","error":"ERROR: Unknown directive type \"program-output\""},{"fix":"Ensure the command is installed and available in the execution environment's PATH. If it's a script from your project, ensure `cwd` is set correctly to the directory containing the script, or provide the full path to the executable. Verify Python virtual environments are correctly activated during the Sphinx build process.","cause":"The command specified in `.. program-output::` or `.. command-output::` cannot be found in the PATH of the environment where Sphinx is being built, or the `cwd` option is pointing to an incorrect directory, or the command itself is not executable. This often occurs when building documentation in a different environment (e.g., CI/CD, ReadTheDocs) than local development.","error":"ERROR: Command 'my_command' failed: [Errno 2] No such file or directory"},{"fix":"Activate your project's virtual environment before running `sphinx-build`. For automated builds (CI/CD, ReadTheDocs), ensure the build process correctly activates the environment or installs all necessary dependencies.","cause":"This specific `ImportError` (or similar for other modules) within `conf.py` when using `sphinxcontrib-programoutput` often indicates that Sphinx is not being run within the correct Python virtual environment that contains all project dependencies, including those needed for `conf.py` itself or by `programoutput`'s execution.","error":"ImportError: No module named 'pbr.version'"}]}