=============================
sphinxcontrib-programoutput
=============================
.. image:: https://github.com/NextThought/sphinxcontrib-programoutput/workflows/tests/badge.svg
:target: https://github.com/NextThought/sphinxcontrib-programoutput/actions?query=workflow%3Atests
.. image:: https://coveralls.io/repos/github/NextThought/sphinxcontrib-programoutput/badge.svg
:target: https://coveralls.io/github/NextThought/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.
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
.. _PyPI: http://pypi.python.org/pypi/sphinxcontrib-programoutput
.. _documentation: http://sphinxcontrib-programoutput.readthedocs.org
=========
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
<https://github.com/NextThought/sphinxcontrib-programoutput/issues/50>`_.
0.16 (2020-03-23)
=================
- Add ``name`` and ``caption`` options. Added in
`PR 41 <https://github.com/NextThought/sphinxcontrib-programoutput/pull/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
<https://github.com/NextThought/sphinxcontrib-programoutput/issues/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
<https://github.com/NextThought/sphinxcontrib-programoutput/issues/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
<https://github.com/NextThought/sphinxcontrib-programoutput/issues/29>`_
by miili.
0.11 (2017-05-18)
=================
- Explicitly set ``parallel_read_safe`` to true in the extension
metadata. See `issue 25
<https://github.com/NextThought/sphinxcontrib-programoutput/issues/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
<https://github.com/habnabit/sphinxcontrib-programoutput/commit/592078e0386c2a36d50a6528b6e49d91707138bf>`_
by Stefan C. Müller.
0.9 (2017-03-15)
================
- Forked and revived the project in `Gitub
<https://github.com/NextThought/sphinxcontrib-programoutput>`_.
- 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
<https://github.com/NextThought/sphinxcontrib-programoutput/issues/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
Raw data
{
"_id": null,
"home_page": "https://sphinxcontrib-programoutput.readthedocs.org/",
"name": "sphinxcontrib-programoutput",
"maintainer": "Jason Madden",
"docs_url": null,
"requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*",
"maintainer_email": "jason@nextthought.com",
"keywords": "sphinx cli command output program example",
"author": "Sebastian Wiesner",
"author_email": "lunaryorn@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/49/fe/8a6d8763674b3d3814a6008a83eb8002b6da188710dd7f4654ec77b4a8ac/sphinxcontrib-programoutput-0.17.tar.gz",
"platform": "any",
"description": "=============================\n sphinxcontrib-programoutput\n=============================\n\n.. image:: https://github.com/NextThought/sphinxcontrib-programoutput/workflows/tests/badge.svg\n :target: https://github.com/NextThought/sphinxcontrib-programoutput/actions?query=workflow%3Atests\n\n.. image:: https://coveralls.io/repos/github/NextThought/sphinxcontrib-programoutput/badge.svg\n :target: https://coveralls.io/github/NextThought/sphinxcontrib-programoutput\n\n\nhttps://sphinxcontrib-programoutput.readthedocs.org\n\nA Sphinx_ extension to literally insert the output of arbitrary commands into\ndocuments, helping you to keep your command examples up to date.\n\n\nInstallation\n============\n\nInstall this extension from PyPI_::\n\n pip install sphinxcontrib-programoutput\n\nThe extension requires Sphinx 1.7.0 and Python 2.7 or Python 3 (Python\n3.6+ is tested) at least.\n\nUsage\n=====\n\nJust add this extension to ``extensions``::\n\n extensions = ['sphinxcontrib.programoutput']\n\nNow you've two new directives ``program-output`` and ``command-output`` to\ninsert the output of programs. The former just inserts the output::\n\n .. program-output:: python -V\n\nOutput::\n\n Python 2.7.1\n\nThe latter directive mimics a shell session, and is intended to show examples::\n\n .. command-output:: python -V\n\nOutput::\n\n $ python -V\n Python 2.7.1\n\n\nPlease refer to the documentation_ for comprehensive information about usage and\nconfiguration of this extension.\n\n\nDevelopment and Support\n=======================\n\nPlease refer to the documentation_ for information on support and the\ndevelopment process.\n\n\n.. _Sphinx: http://www.sphinx-doc.org/en/stable/\n.. _PyPI: http://pypi.python.org/pypi/sphinxcontrib-programoutput\n.. _documentation: http://sphinxcontrib-programoutput.readthedocs.org\n\n\n=========\n Changes\n=========\n\n0.17 (2021-03-31)\n=================\n\n- Add support for Python 3.9.\n\n- Drop support for python 3.5.\n\n- Include program output and current working directory in the warning\n logged when a program returns an unexpected return code. Suggested\n by Sorin Sbarnea. See `issue 50\n <https://github.com/NextThought/sphinxcontrib-programoutput/issues/50>`_.\n\n\n0.16 (2020-03-23)\n=================\n\n- Add ``name`` and ``caption`` options. Added in\n `PR 41 <https://github.com/NextThought/sphinxcontrib-programoutput/pull/41>`_\n by Rapha\u00ebl.\n- Add support for Python 3.8.\n\n\n0.15 (2019-09-16)\n=================\n\n- Make the test suite stop assuming the presence of a 'python'\n executable on the path. Instead it uses ``sys.executable`` (which\n shouldn't have spaces). Note that it does continue to assume the\n presence of other executables, such as 'echo'. Reported in `issue 38\n <https://github.com/NextThought/sphinxcontrib-programoutput/issues/38>`_\n by John Vandenberg.\n\n\n0.14 (2019-04-08)\n=================\n\n- Add ``python_requires`` metadata to better allow tools like ``pip``\n to install a correct version.\n\n- Add support for Sphinx 2.0 on Python 3.\n\n- Avoid unicode errors when the program command or output produced\n non-ASCII output and the configured prompt was a byte string. This\n was most likely under Python 2, where the default configured prompt\n is a byte string. Reported by, and patch inspired by, `issue 33\n <https://github.com/NextThought/sphinxcontrib-programoutput/issues/33>`_\n by latricewilgus.\n\n0.13 (2018-12-22)\n=================\n\n- Drop support for Sphinx < 1.7.\n\n- Fix tests on Sphinx >= 1.8.0.\n\n- Restore error message into the document by default from failed\n program runs on Sphinx >= 1.8.0b1.\n\n- Fix deprecation warnings on Sphinx >= 1.8. Reported in `issue 29\n <https://github.com/NextThought/sphinxcontrib-programoutput/issues/29>`_\n by miili.\n\n\n0.11 (2017-05-18)\n=================\n\n- Explicitly set ``parallel_read_safe`` to true in the extension\n metadata. See `issue 25\n <https://github.com/NextThought/sphinxcontrib-programoutput/issues/25>`_.\n With thanks to Adam J. Stewart and Stephen McDowell.\n\n0.10 (2017-03-17)\n=================\n\n- Decode output from the program tolerantly, using the 'replace'\n handler. Based on a `pull request\n <https://github.com/habnabit/sphinxcontrib-programoutput/commit/592078e0386c2a36d50a6528b6e49d91707138bf>`_\n by Stefan C. M\u00fcller.\n\n\n0.9 (2017-03-15)\n================\n\n- Forked and revived the project in `Gitub\n <https://github.com/NextThought/sphinxcontrib-programoutput>`_.\n\n- Run the tests on Travis CI. Formatting and style is enforced by pylint.\n\n- The oldest supported and tested Sphinx version is now 1.3.5. See\n `issue 17\n <https://github.com/NextThought/sphinxcontrib-programoutput/issues/17>`_.\n\n\n- Remove support for Python 2.6, Python 3.2 and 3.3.\n\n- 100% test coverage.\n\n- Remove support for ``programoutput_use_ansi``. The\n ``sphinxcontrib.ansi`` extension is no longer available on PyPI.\n\n0.8 (Oct 12, 2012)\n==================\n\n- Migrated to GitHub\n\n\n0.7 (Apr 17, 2012)\n==================\n\n- Added ``cwd`` option to ``..program-output``\n- Working directory of executed programs defaults to documentation root now\n\n\n0.6 (Jan 07, 2012)\n==================\n\n- Python 3 support\n- Require Sphinx 1.1 now\n\n\n0.5 (Sep 19, 2011)\n==================\n\n- ``programoutput_prompt_template`` is interpreted as format string now!\n- Require Python 2.6 now\n- Added ``returncode`` option to ``program-output`` (thanks to\n Jan-Marek Glogowski)\n- Support ``returncode`` formatting key in\n ``programoutput_prompt_template``\n- Warn on unexpected return codes instead of raising\n ``subprocess.CalledProcessError``\n- Turn fatal errors during command into document error messages\n instead of crashing the build\n\n\n0.4.1 (Mar 11, 2011)\n====================\n\n- Some source code cleanups\n- Fixed installation instructions in documentation\n\n\n0.4 (May 21, 2010)\n==================\n\n- Initial release\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Sphinx extension to include program output",
"version": "0.17",
"split_keywords": [
"sphinx",
"cli",
"command",
"output",
"program",
"example"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "97ee90a39f03be83320bca30c7d202f0",
"sha256": "0ef1c1d9159dbe7103077748214305eb4e0138e861feb71c0c346afc5fe97f84"
},
"downloads": -1,
"filename": "sphinxcontrib_programoutput-0.17-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "97ee90a39f03be83320bca30c7d202f0",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*",
"size": 22131,
"upload_time": "2021-03-31T15:00:01",
"upload_time_iso_8601": "2021-03-31T15:00:01.402230Z",
"url": "https://files.pythonhosted.org/packages/30/ee/b7be4b3f45f4e36bfa6c444cd234098e0d09880379c67a43e6bb9ab99a86/sphinxcontrib_programoutput-0.17-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "7bad912b0af6bb504819659ffe382199",
"sha256": "300ee9b8caee8355d25cc74b4d1c7efd12e608d2ad165e3141d31e6fbc152b7f"
},
"downloads": -1,
"filename": "sphinxcontrib-programoutput-0.17.tar.gz",
"has_sig": false,
"md5_digest": "7bad912b0af6bb504819659ffe382199",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*",
"size": 24067,
"upload_time": "2021-03-31T15:00:02",
"upload_time_iso_8601": "2021-03-31T15:00:02.852868Z",
"url": "https://files.pythonhosted.org/packages/49/fe/8a6d8763674b3d3814a6008a83eb8002b6da188710dd7f4654ec77b4a8ac/sphinxcontrib-programoutput-0.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-03-31 15:00:02",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "sphinxcontrib-programoutput"
}
JSON