sphinxcontrib-programoutput 0.17

Sphinx extension to include program output

sphinxcontrib-programoutput

https://sphinxcontrib-programoutput.readthedocs.org

A Sphinx extension to literally insert the output of arbitrary commands into documents, helping you to keep your command examples up to date.

Installation

Install this extension from PyPI:

pip install sphinxcontrib-programoutput

The extension requires Sphinx 1.7.0 and Python 2.7 or Python 3 (Python 3.6+ is tested) at least.

Usage

Just 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. The former just inserts the output:

.. program-output:: python -V

Output:

Python 2.7.1

The latter directive mimics a shell session, and is intended to show examples:

.. command-output:: python -V

Output:

$ python -V
Python 2.7.1

Please refer to the documentation for comprehensive information about usage and configuration of this extension.

Development and Support

Please refer to the documentation for information on support and the development process.

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