Sphinx extension to insert the output of arbitrary commands into documents.
The extension is available under the terms of the BSD license.
Use pip to install this extension from the Cheeseshop:
pip install sphinxcontrib-programoutput
The extension requires Sphinx 1.1 and Python 2.6 or Python 3.1 at least.
To include the output of a command into your document, use the 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.
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.
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:
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.
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:
usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ... Options and arguments (and corresponding environment variables): ... str, bytes and datetime objects. It can also be set to an integer in the range [0,4294967295] to get hash values with a predictable seed.
.. command-output:: python -V
$ python -V Python 2.7.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:: python --help :ellipsis: 2
$ python --help usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ... Options and arguments (and corresponding environment variables): ...
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 "$USER"
$ echo "$USER" $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:
$ echo "$USER" docs
Other shell features like process expansion consequently work, too:
.. command-output:: ls -l $(which grep) :shell:
$ ls -l $(which grep) -rwxr-xr-x 1 root root 159288 Dec 16 2011 /bin/grep
Remember to use shell carefully to avoid unintented interpretation of shell syntax and swallowing of fatal errors!
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 sys.exit()), but no warning will be emitted. On the contrary, a warning will be emitted, should the command return 0!
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.
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 controlls 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.
This extension understands the following configuration options:
$ python -V Python 2.7.3
The following keys are provided to the format string:
Please report issues to the issue tracker if you have trouble or found a bug in this extension, but respect the following guidelines:
The source code is hosted on Github:
git clone https://github.com/lunaryorn/sphinxcontrib-programoutput
Please fork the repository and send pull requests with your fixes or features, but respect these guidelines:
Copyright (c) 2010, 2011, 2012 Sebastian Wiesner <firstname.lastname@example.org> 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.
|||This directive is just an alias for the program-output directive with the prompt option set.|