Skip to main content

Sphinx extension to include program output

Project description

sphinxcontrib-programoutput

https://secure.travis-ci.org/NextThought/sphinxcontrib-programoutput.png https://coveralls.io/repos/github/NextThought/sphinxcontrib-programoutput/badge.svg

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.5+ 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.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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinxcontrib-programoutput, version 0.16
Filename, size File type Python version Upload date Hashes
Filename, size sphinxcontrib_programoutput-0.16-py2.py3-none-any.whl (21.8 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size sphinxcontrib-programoutput-0.16.tar.gz (23.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page