Source

sphinx-contrib / programoutput / doc / index.rst

:py:mod:`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, see LICENSE for more information.

Installation

This extension requires Sphinx 1.1 and at least Python 2.6 or Python 3.2. It is available in the Python Package Index:

pip install sphinxcontrib-programoutput

Alternatively, you can clone the sphinx-contrib repository from BitBucket, and install the extension directly from the repository:

hg clone https://bitbucket.org/birkenfeld/sphinx-contrib
cd sphinx-contrib/programoutput
python setup.py install

Usage

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

.. program-output:: python -V

The whole output of python -V, 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.

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:: python --help
   :ellipsis: 2

The above omits all lines after the second one:

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:: python --help
   :ellipsis: 2,-2

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

Mimicing shell input

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

.. command-output:: python -V

The appearance of this output can be configured with :confval:`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:: python --help
   :ellipsis: 2

Command execution and shell expansion

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

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

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

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

Other shell features like process expansion consequently work, too:

.. command-output:: ls -l $(which grep)
   :shell:

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:: python -c 'import sys; sys.exit(1)'
   :returncode: 1

The above command returns the exit code 1 (as given to :py:func:`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

Configuration

This extension understands the following configuration options:

Contribution

Please contact the author or create an issue in the issue tracker of the sphinx-contrib repository, if you have found any bugs or miss some functionality (e.g. integration of some other issue tracker). Patches are welcome!

Footnotes

[1]This directive is just an alias for the :dir:`program-output` directive with the prompt option set.