Table Of Contents

Previous topic

Welcome to lunar.sphinx.ext’s documentation!

Next topic

lunar.sphinx.ext.ansi – Parse ANSI control sequences

This Page

lunar.sphinx.ext.programoutput – Include program output

This extension allows you to run programs during the build process, and include their output into the documentation.

It adds this main directive:

.. program-output::

This directive accepts a single string as argument, which is the command to execute. By default, this command string is split using the shlex modules, which mostly works like common Unix shells like bash or zsh:

.. program-output:: python -V

The above snippet would render like this:

Python 2.6.5

However, special shell features like parameter expansion are not supported:

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

To enable such shell features, use option shell. If this option is given, the command string is executed using /bin/sh -c:

.. program-output:: echo "$USER"
   :shell:
lunar

By default, both standard output and standard error are captured and included in the document. Use option nostderr to hide anything from the standard error stream of the invoked program.

You can include the command, which produced the output, by specified option prompt. The result will mimic input on a shell prompt with the resulting output:

.. program-output:: python -V
   :prompt:
$ python -V
Python 2.6.5

The prompt can be configured using programoutput_prompt_template. The directive command-output provides a convenient shortcut to this directive with prompt.

Sometimes the program may require options, you may not want to include in the prompt. You can use the extraargs option for this purpose. The value of this options is parsed just like the command itself, and afterwards appended to the command. It will however never appear in the output, if prompt is specified.

You can shorten the output of programs using the ellipsis option. This option accepts at most two comma-separated integers, which refer to lines in the output. If the second integer is missing, it refers to the last line. Everything in between these lines is replaced by a single ellipsis ...:

.. program-output::  python --help
   :prompt:
   :ellipsis: 2
$ python –help
usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ...
Options and arguments (and corresponding environment variables):
...

Negative line numbers are counted from the last-line. Thus specifying :ellipsis:  2, -2 will remove anything except the first two and the last two lines:

.. program-output::  python --help
   :prompt:
   :shell:
   :ellipsis: 2, -2
$ python –help
usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ...
Options and arguments (and corresponding environment variables):
...
PYTHONCASEOK : ignore case in ‘import’ statements (Windows).
PYTHONIOENCODING: Encoding[:errors] used for stdin/stdout/stderr.
.. command-output::
Just like program-output, but with prompt enabled.

Configuration

This extension understands the following configuration options:

programoutput_prompt_template
This configuration value defines the looks of the output of command-output and program-output with option prompt. The default value is $ %(command)s\n%(output)s. The key command is replaced with the command, the key output with the output of this command.
programoutput_use_ansi
Interpret ANSI colour sequences in program output. The extension lunar.sphinx.ext.ansi must be enabled and configuration for this to work properly.