2.4. Program Output

PyPI Package

https://pypi.org/project/sphinxcontrib-programoutput/

Documentation

https://sphinxcontrib-programoutput.readthedocs.org/

Git Repository

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

Literally insert the output of arbitrary commands into documents, helping you to keep your command examples up to date. It consists:

2.4.1. Complete output

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

.. program-output::

For more details, see program-output directive.

The example
1
.. program-output:: python --version
Which gives
Python 3.8.0

The whole output of python --version, including any messages on standard error, is inserted into the current document, formatted as literal text without any syntax highlighting. 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.

2.4.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.

the example

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

1
2
.. program-output:: python --help
   :ellipsis: 2
which gives

The above omits all lines after the second one:

usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ...
Options and arguments (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.

the example

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:

1
2
3
4
.. program-output:: python --help
   :caption: First two and last second lines from :command:`python --help`
   :name: program-output-python-help
   :ellipsis: 2,-2
which gives

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

Listing 2.2 First two and last second lines from python --help
usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ...
Options and arguments (and corresponding environment variables):
...
PYTHONDEVMODE: enable the development mode.
PYTHONPYCACHEPREFIX: root directory for bytecode cache (pyc) files.

2.4.3. Mimicking 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::

For more details, see command-output directive.

The example
1
.. command-output:: python --version
Which gives
$ python --version
Python 3.8.0

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.

the example
1
2
3
4
.. command-output:: python --help
   :caption: First two lines from :command:`python --help` with prompt
   :name: command-output-python-help
   :ellipsis: 2
which gives
Listing 2.3 First two lines from python --help with prompt
$ python --help
usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ...
Options and arguments (and corresponding environment variables):
...

2.4.4. Command execution and shell expansion

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

the example
1
.. command-output:: echo "$USER"
which gives
$ echo "$USER"
$USER

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

the example
1
2
.. command-output:: echo "$USER"
   :shell:
which gives
$ echo "$USER"

Other shell features like process expansion consequently work, too.

the example
1
2
.. command-output:: ls -l $(which grep)
   :shell:
which gives
$ ls -l $(which grep)
-rwxr-xr-x 1 root root 219456 Sep 18  2019 /bin/grep

Warning

Remember to use :shell: carefully to avoid unintended interpretation of shell syntax and swallowing of fatal errors!

2.4.5. 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.

the example
1
2
.. command-output:: python -c 'import sys, platform; print(sys.version); sys.exit(1)'
   :returncode: 1
which gives
$ python -c 'import sys, platform; print(sys.version); sys.exit(1)'
3.8.0 (default, Jan 24 2020, 02:13:43) 
[GCC 7.4.0]

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.

Footnotes

1

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