# `sphinxcontrib.programoutput` – Insert command output

Sphinx extension to insert the output of arbitrary commands into documents.

The extension is available under the terms of the BSD license.

## Installation

Use `pip` to install this extension from PyPI:

    pip install sphinxcontrib-programoutput

The extension requires Sphinx 1.3 and Python 2.7 or Python 3 at least.

You can now add this extension to `extensions`:

    extensions = ['sphinxcontrib.programoutput']

Now you’ve two new directives `program-output` and `command-output` to insert the output of programs.

## Usage

To include the output of a command into your document, use the `program-output` directive provided by this extension:

    .. program-output:: python3 -V

The whole output of `python3 -V`, including any messages on standard error, is inserted into the current document, formatted as literal text without any syntax highlighting:

    Python 3.14.3

You can omit the content of the standard error stream with the `nostderr` option.

By default, commands are executed in the top-level source directory. You can choose an alternate working directory with the `cwd` option. The argument of this option is either a path relative to the current source file, or a absolute path which means that it is relative to the top level source directory.

## Usage with MyST (Markdown)

If you are using MyST, the directive would look like:

    ```{program-output} python -V
    ---
    ellipsis: 2
    ---
    ```

### Shortening the output

Lengthy output can be shortened with the `ellipsis` option. Its value denotes lines to omit when inserting the output of the command. Instead, a single ellipsis `...` is inserted.

If used with a single number, all lines after the specified line are omitted:

    .. program-output:: python3 --help
       :ellipsis: 2

The above omits all lines after the second one:

    usage: python3 [option] ... [-c cmd | -m mod | file | -] [arg] ...
    Options (and corresponding environment variables):
    ...

Negative numbers count from the last line backwards, thus replacing `2` with `-2` in the above example would only omit the last two lines.

If used with two comma-separated line numbers, all lines in between the specified lines are omitted. Again, a negative number counts from the last line backwards:

    .. program-output:: python3 --help
       :ellipsis: 2,-2

The above omits all lines except the first two and the last two lines:

    usage: python3 [option] ... [-c cmd | -m mod | file | -] [arg] ...
    Options (and corresponding environment variables):
    ...
    -      : program read from stdin (default; interactive mode if a tty)
    arg ...: arguments passed to program in sys.argv[1:]

### Mimicing shell input

You can mimic shell input with the `command-output` directive [1]. This directive inserts the command along with its output into the document:

    .. command-output:: python3 -V

    $ python3 -V
    Python 3.14.3

The appearance of this output can be configured with `programoutput_prompt_template`. When used in conjunction with `ellipsis`, the command itself and any additional text is never omitted. `ellipsis` always refers to the immediate output of the command:

    .. command-output:: python3 --help
       :ellipsis: 2

    $ python3 --help
    usage: python3 [option] ... [-c cmd | -m mod | file | -] [arg] ...
    Options (and corresponding environment variables):
    ...

### Command execution and shell expansion

Normally the command is splitted according to the POSIX shell syntax (see `shlex`), and executed directly. Thus special shell features like expansion of environment variables will not work:

    .. command-output:: echo "$SHELL"

    $ echo "$SHELL"
    $SHELL

To enable these features, enable the `shell` option. With this option, the command is literally passed to the system shell:

    .. command-output:: echo "$SHELL"
       :shell:

    $ echo "$SHELL"
    /bin/sh

Other shell features like process expansion consequently work, too:

    .. command-output:: test -x $(command -v grep) && echo yes
       :shell:

    $ test -x $(command -v grep) && echo yes
    yes

Remember to use `shell` carefully to avoid unintented interpretation of shell syntax and swallowing of fatal errors!

### Error handling

If an unexpected exit code (also known as return code) is returned by a command, it is considered to have failed. In this case, a build warning is emitted to help you to detect misspelled commands or similar errors. By default, a command is expected to exit with an exit code of 0, all other codes indicate an error. In some cases however, it may be reasonable to demonstrate failed programs. To avoid a (superfluous) warning in such a case, you can specify the expected return code of a command with the `returncode` option:

    .. command-output:: python3 -c 'import sys; sys.exit(1)'
       :returncode: 1

The above command returns the exit code 1 (as given to `sys.exit()`), but no warning will be emitted. On the contrary, a warning will be emitted, should the command return 0!

Note

Upon fatal errors which even prevent the execution of the command neither return code nor command output are available. In this case an error message is inserted into the document instead.

If `shell` is set however, most of these fatal errors are handled by the system shell and turned into return codes instead. In this case the error message will only appear in the output of the shell. If you’re using `shell`, double-check the output for errors. Best avoid `shell`, if possible.

## Reference

.. program-output:: command

  Include the output of `command` in the documentation.

  The output is formatted as literal text, without any syntax highlighting.

  By default, the command is split according to the POSIX shell syntax (using `shlex.split()`), and executed directly. Both standard output and standard error are captured from the invocation of `command` and included in the document. However, if the option `shell` is given, `command` is literally passed to the system shell. With the `nostderr` option, standard error is hidden from the output.

  The working directory of the command can be configured with the `cwd` option. The argument of this option is a directory path, relative to the current source file. Absolute paths are interpreted as relative to the root of the source directory. The default working directory is `/`, i.e. the root of the source directory.

  If the `prompt` option is given, the `command` itself is included in the document, so that the output mimics input in a shell prompt. `programoutput_prompt_template` controls the appearance of this. The value of the `extraargs` option is appended at the end of `command` (separated by a whitespace) before executing the command, but not included in the output of the `prompt` option. Use this to pass extra arguments which should not appear in the document.

  The output can be shortened with the `ellipsis` option. The value of this option is of the form `start[,end]` with `start` and `end` being integers which refer to lines in the output of `command`. `end` is optional and defaults to the last line. Negative line numbers count backwards from the last line. Everything in the interval `[start, end[` is replaced with a single ellipsis `...`. The `ellipsis` option only affects the immediate output of `command`, but never any additional text inserted by option `prompt`.

  If the command does return an exit code different from the expected one, a build warning is issued. The expected return code defaults to 0, and can be changed with the `returncode` option.

  A `caption` option can be given to show the given name, or by default the given command, before the output block. A `name` option with a target name can be provided to reference the command block by using `ref`.

  Changed in version 0.16: Add the `caption` and `name` options.

.. command-output::

  Same as `program-output`, but with enabled `prompt` option.

### Configuration

This extension understands the following configuration options:

programoutput_prompt_template

  A format string template for the output of the `prompt` option to `command-output`. Defaults to `$ {command}\n{output}` which renders as follows:

      $ python3 -V
      Python 3.14.3

  The following keys are provided to the format string:

  - `command` is replaced with the literal command as given to the directive, without any `extraargs`.

  - `output` is the output of the command, after the `ellipsis` option has been applied.

  - `returncode` is the return code of the command as integer.

## Support

Please report issues to the issue tracker if you have trouble or found a bug in this extension, but respect the following guidelines:

- Check that the issue has not already been reported.

- Check that the issue is not already fixed in the `master` branch.

- Open issues with clear title and a detailed description in grammatically correct, complete sentences.

## Development

The source code is hosted on Github:

    git clone https://github.com/NextThought/sphinxcontrib-programoutput

Please fork the repository and send pull requests with your fixes or features, but respect these guidelines:

- Read how to properly contribute to open source projects on GitHub.

- Use a topic branch to easily amend a pull request later, if necessary.

- Write good commit messages.

- Squash commits on the topic branch before opening a pull request.

- Respect PEP 8 (use pep8 to check your coding style compliance)

- Add unit tests.

- Open a new pull request that relates to but one subject with a clear title and description in grammatically correct, complete sentences.

## Changelog

# Changes

## 0.17 (2021-03-31)

- Add support for Python 3.9.

- Drop support for python 3.5.

- Include program output and current working directory in the warning logged when a program returns an unexpected return code. Suggested by Sorin Sbarnea. See issue 50.

## 0.16 (2020-03-23)

- Add `name` and `caption` options. Added in PR 41 by Raphaël.

- Add support for Python 3.8.

## 0.15 (2019-09-16)

- Make the test suite stop assuming the presence of a ‘python’ executable on the path. Instead it uses `sys.executable` (which shouldn’t have spaces). Note that it does continue to assume the presence of other executables, such as ‘echo’. Reported in issue 38 by John Vandenberg.

## 0.14 (2019-04-08)

- Add `python_requires` metadata to better allow tools like `pip` to install a correct version.

- Add support for Sphinx 2.0 on Python 3.

- Avoid unicode errors when the program command or output produced non-ASCII output and the configured prompt was a byte string. This was most likely under Python 2, where the default configured prompt is a byte string. Reported by, and patch inspired by, issue 33 by latricewilgus.

## 0.13 (2018-12-22)

- Drop support for Sphinx < 1.7.

- Fix tests on Sphinx >= 1.8.0.

- Restore error message into the document by default from failed program runs on Sphinx >= 1.8.0b1.

- Fix deprecation warnings on Sphinx >= 1.8. Reported in issue 29 by miili.

## 0.11 (2017-05-18)

- Explicitly set `parallel_read_safe` to true in the extension metadata. See issue 25. With thanks to Adam J. Stewart and Stephen McDowell.

## 0.10 (2017-03-17)

- Decode output from the program tolerantly, using the ‘replace’ handler. Based on a pull request by Stefan C. Müller.

## 0.9 (2017-03-15)

- Forked and revived the project in Gitub.

- Run the tests on Travis CI. Formatting and style is enforced by pylint.

- The oldest supported and tested Sphinx version is now 1.3.5. See issue 17.

- Remove support for Python 2.6, Python 3.2 and 3.3.

- 100% test coverage.

- Remove support for `programoutput_use_ansi`. The `sphinxcontrib.ansi` extension is no longer available on PyPI.

## 0.8 (Oct 12, 2012)

- Migrated to GitHub

## 0.7 (Apr 17, 2012)

- Added `cwd` option to `..program-output`

- Working directory of executed programs defaults to documentation root now

## 0.6 (Jan 07, 2012)

- Python 3 support

- Require Sphinx 1.1 now

## 0.5 (Sep 19, 2011)

- `programoutput_prompt_template` is interpreted as format string now!

- Require Python 2.6 now

- Added `returncode` option to `program-output` (thanks to Jan-Marek Glogowski)

- Support `returncode` formatting key in `programoutput_prompt_template`

- Warn on unexpected return codes instead of raising `subprocess.CalledProcessError`

- Turn fatal errors during command into document error messages instead of crashing the build

## 0.4.1 (Mar 11, 2011)

- Some source code cleanups

- Fixed installation instructions in documentation

## 0.4 (May 21, 2010)

- Initial release

## License

    Copyright (c) 2010, 2011, 2012 Sebastian Wiesner <lunaryorn@googlemail.com>
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are
    met:

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Footnotes

[1]

This directive is just an alias for the `program-output` directive with the `prompt` option set.