opennti/sphinxcontrib-programoutput

Sphinx extension for capturing 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.

sphinxcontrib-programoutput's Issues

Travis CI

Document use with myst

Some projects started to use markdown instead of RST with Sphinx. It would be really handy to document how to use programoutput with https://myst-parser.readthedocs.io/en/latest/

Updating documentation should not be hard to include a markdown version of it:

```{command-output} python -V
```

Still, I need to remark that I observed one case where using shell pipes no longer works: if you command was something like bash -c "ls | grep foo", you may discover that the pipe filtering is lost and you get the full output. Anyway, this is likely a bug in myst argument parsing and not in programoutput extension.

Cannot handle Unicode characters with Python 2.7

See description of pull request #32.

Move away from pytest to just unittest

Update links

tox -e doc reports some links that are redirects that we should update:

(line  106) ok        https://docs.python.org/2/library/shlex.html#module-shlex
(line  175) ok        https://docs.python.org/2/library/shlex.html#shlex.split
(line  149) ok        https://docs.python.org/2/library/sys.html#sys.exit
(line   18) redirect  http://pypi.python.org/pypi/sphinxcontrib-programoutput - permanently to https://pypi.python.org/pypi/sphinxcontrib-programoutput
(line  221) redirect  http://docs.python.org/library/string.html#formatstrings - permanently to https://docs.python.org/3/library/string.html#formatstrings
(line  237) ok        https://pythonhosted.org/sphinxcontrib-ansi/index.html#module-sphinxcontrib.ansi
(line  246) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues
(line  268) ok        http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
(line  258) ok        https://github.com/NextThought/sphinxcontrib-programoutput
(line  273) ok        https://help.github.com/articles/using-pull-requests
(line   10) redirect  http://sphinx.pocoo.org/ - with Found to http://www.sphinx-doc.org/en/stable/
(line  265) redirect  http://gun.io/blog/how-to-github-fork-branch-and-pull-request/ - permanently to https://gun.io/blog/how-to-github-fork-branch-and-pull-request/
(line   41) ok        https://docs.python.org/2/library/subprocess.html#subprocess.CalledProcessError
(line    9) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues/17
(line  271) redirect  http://pypi.python.org/pypi/pep8/ - permanently to https://pypi.python.org/pypi/pep8/
(line  271) ok        https://www.python.org/dev/peps/pep-0008

Caching to disk - PR suggestion

First, thank you for creating this extension and publishing it. I found it very useful!
The current cache mechanism is only in memory, and it's no so straight how to add on disk caching.
Further, if you try adding a cache mechanism trough conf.py you will bump into pickle errors.
Hence, I forked this extension and created a JSONCache class which saved the commands
and output to disk.
It's useful in cases you do 'make clean' but don't want your commands
to run again for a couple of possible reasons:

• long execution time - more commands means longer build process
• expensive execution time, for example: your command create cloud infrastructure ...

My code works, but it still lacks tests. However, if you are interested in it, I will open a PR and
we can discuss what is the best approach to create effective tests.

Update all project URLs

[feature] customize language

new_node['language'] = 'text'

Why not allow user to change a language?

0.17: sphins 4.1.1 warnings

Looks like python executable name is hardcoded doc/index.rst

+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.1.1
making output directory... done
loading intersphinx inventory from https://docs.python.org/objects.inv...
loading intersphinx inventory from http://packages.python.org/sphinxcontrib-ansi/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
intersphinx inventory has moved: http://packages.python.org/sphinxcontrib-ansi/objects.inv -> https://pythonhosted.org/sphinxcontrib-ansi/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/doc/index.rst:44: WARNING: Command ['python', '-V'] failed: [Errno 2] No such file or directory: 'python'
/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/doc/index.rst:79: WARNING: Command ['python', '--help'] failed: [Errno 2] No such file or directory: 'python'
/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/doc/index.rst:94: WARNING: Command ['python', '--help'] failed: [Errno 2] No such file or directory: 'python'
/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/doc/index.rst:106: WARNING: Command ['python', '-V'] failed: [Errno 2] No such file or directory: 'python'
/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/doc/index.rst:116: WARNING: Command ['python', '--help'] failed: [Errno 2] No such file or directory: 'python'
/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/doc/index.rst:250: WARNING: Command ['python', '-V'] failed: [Errno 2] No such file or directory: 'python'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinxcontrib-programoutput.3 { } done
build succeeded, 6 warnings.

stdout/stderr is missing when build fails due to unexpected return code

At this moment, if documentation building is failing because one of the output commands is returning an unexpected exit code, we have no clue about what could have caused it as it lacks any other information.

Example:

Warning, treated as error:
Unexpected return code 1 from command 'yarnpkg --non-interactive --cwd=web run'
ERROR: InvocationError for command /home/ssbarnea/rmux/zuul/.tox/docs/bin/sphinx-build -E -W -d doc/build/doctrees -b html doc/source/ doc/build/html (exited with code 2)

Essential debugging info:

• command line
• current working directory (can often impact the result)
• stdout
• stderr

It would extremely useful to include these missing bits when this happens, especially as running the same command outside sphinx may work. I should remark that I faced this issue on two different and unrelated projects, so is not really uncommon.

Please note that I would be happy to provide a pull-request that address this issue, but I would like to hear the maintainer opinion before doing the work to implement that, especially as the current implementation is using a tuple to return results, something that is not really nice/easy to extend.

Currently something like (result, output) is passed across several functions and adding cwd would make it look like result, output, cwd). That is one moment where you realised that using a CompletedProcess produced by subprocess.run would have being much nicer.

Test old sphinx

Currently we're testing the latest available sphinx. We should also test back to the oldest version we actually want to support.

Documents claim 1.1 is supported. That dates to late 2011.

ReadTheDocs uses Sphinx 1.3.5 by default (I think), which dates to 2016. That seems like a reasonable version to cut support with.

how to use programoutput_use_ansi

I am looking at https://pythonhosted.org/sphinxcontrib-programoutput/#confval-programoutput_use_ansi but its not clear how to use ansi color in sphinx. It would help if i can have some more documentation. I see this relies on https://pythonhosted.org/sphinxcontrib-ansi/index.html#sphinxcontrib.ansi but i can't seem to find this project on bitbucket and seems like this project. I am not sure if this project ceased development. How can i work around getting ansi color in sphinx so its rendered properly. If not i need way to disable coloring or apply some sed scripts to strip them out

Compatibility with pytest 8

When I run the tests with pytest 8.2.0, I get the following errors:

=================================== FAILURES ===================================
_____________ TestDirective.test_shell_with_unexpected_return_code _____________

self = <programoutput.tests.test_directive.TestDirective testMethod=test_shell_with_unexpected_return_code>

    @with_content("""\
    .. program-output:: python3 -c 'import sys; sys.exit("some output")'
       :shell:""",
                  ignore_warnings=False)
    def test_shell_with_unexpected_return_code(self):
        with self.assertRaises(SphinxWarning) as excinfo:
            self.app.build()
        msg = excinfo.exception.args[0]
>       self.assertIn('Unexpected return code 1 from command',
                      msg)
E       AssertionError: 'Unexpected return code 1 from command' not found in "directive 'deprecated' is already registered, it will be overridden"

../../BUILDROOT/python-sphinxcontrib-programoutput-0.17-13.fc41.x86_64/usr/lib/python3.12/site-packages/sphinxcontrib/programoutput/tests/test_directive.py:308: AssertionError
__________________ TestDirective.test_unexpected_return_code ___________________

self = <programoutput.tests.test_directive.TestDirective testMethod=test_unexpected_return_code>

    @with_content("""\
    .. program-output:: python3 -c 'import sys; sys.exit(1)'""",
                  ignore_warnings=False)
    def test_unexpected_return_code(self):
        with self.assertRaises(SphinxWarning) as excinfo:
            self.app.build()
>       self.assertIn('Unexpected return code 1 from command',
                      excinfo.exception.args[0])
E       AssertionError: 'Unexpected return code 1 from command' not found in "directive 'deprecated' is already registered, it will be overridden"

../../BUILDROOT/python-sphinxcontrib-programoutput-0.17-13.fc41.x86_64/usr/lib/python3.12/site-packages/sphinxcontrib/programoutput/tests/test_directive.py:293: AssertionError
=========================== short test summary info ============================
FAILED ../../BUILDROOT/python-sphinxcontrib-programoutput-0.17-13.fc41.x86_64/usr/lib/python3.12/site-packages/sphinxcontrib/programoutput/tests/test_directive.py::TestDirective::test_shell_with_unexpected_return_code
FAILED ../../BUILDROOT/python-sphinxcontrib-programoutput-0.17-13.fc41.x86_64/usr/lib/python3.12/site-packages/sphinxcontrib/programoutput/tests/test_directive.py::TestDirective::test_unexpected_return_code
=========== 2 failed, 60 passed, 1 deselected, 67 warnings in 4.64s ============

Enforce coding style

Run pylint or prospector during the build on Travis, fail the build if it fails.

[Request] Interpret output instead of inserting it

Dear developer,

I was searching for an extension that inserts program output to rst document and found yours exactly matching my needs. Thanks a lot.

Now I have a feature request. Instead of inserting the program output, I'd like the output to be interpreted as ReST content. Usage is the following: We have some transform programs that extract data from custom file formats and turn them into ReST content. We would like to insert that content into our documentation while generating the doc. Something like this would be nice:

.. program-interpret-output: mytransform.py mydata.bin

The mytransform.py would be searched in a location stored in a custom program-output variable in conf.py.

Thanks a lot.

Using cwd option

Hi, thanks for this extension it is super useful for auto documenting cli tools!

One thing I can't get to work though is to get the "cwd" option. I don't think the documentation tells how this option should be used?

Note that I am trying to get this work with Sphinx+MyST, so what I am trying is the following (note I am using 3x acute tilde so they are not incorrectly interpreted here)

´´´{command-output} pwd
---
cwd ..
---
´´´

This is, I am just trying to go up one folder before I can execute "pwd". However I get a big error when doing so:

File "*****/.venv/lib/python3.9/site-packages/myst_parser/parsers/directives.py", line 144, in parse_directive_options
    for name, value in list(options.items()):
AttributeError: 'str' object has no attribute 'items'
The full traceback has been saved in /tmp/sphinx-err-l59_ympn.log, if you want to report the issue to the developers.

Actually, what I would really like to get more info about is regarding on what environment are these commands really running on. This is, on what shell environment is this running? I guess on a one provided by python's subprocess? Is it possible to update $PATH document-wide via some python command on conf.py?

Thanks

Remove `unicode_literals`

0.17: tox based test suite is failing

+ cd sphinxcontrib-programoutput-0.17
+ /usr/bin/python3 -Bm tox --skip-missing-interpreters
py27 create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/py27
SKIPPED: InterpreterNotFound: python2.7
py27-old create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/py27-old
SKIPPED: InterpreterNotFound: python2.7
py36 create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/py36
SKIPPED: InterpreterNotFound: python3.6
py37 create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/py37
SKIPPED: InterpreterNotFound: python3.7
py38 create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/py38
py38 installdeps: pylint, coverage
py38 develop-inst: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17
py38 installed: alabaster==0.7.12,astroid==2.5.6,Babel==2.9.0,certifi==2020.12.5,chardet==4.0.0,coverage==5.5,docutils==0.16,idna==2.10,imagesize==1.2.0,isort==5.8.0,Jinja2==2.11.3,lazy-object-proxy==1.6.0,MarkupSafe==1.1.1,mccabe==0.6.1,packaging==20.9,Pygments==2.8.1,pylint==2.8.2,pyparsing==2.4.7,pytz==2021.1,requests==2.25.1,snowballstemmer==2.1.0,Sphinx==3.5.4,sphinxcontrib-applehelp==1.0.2,sphinxcontrib-devhelp==1.0.2,sphinxcontrib-htmlhelp==1.0.3,sphinxcontrib-jsmath==1.0.1,# Editable install with no version control (sphinxcontrib-programoutput==0.17),-e /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/src,sphinxcontrib-qthelp==1.0.3,sphinxcontrib-serializinghtml==1.1.4,toml==0.10.2,urllib3==1.26.4,wrapt==1.12.1
py38 run-test-pre: PYTHONHASHSEED='2428015188'
py38 run-test: commands[0] | coverage run -p -m unittest discover -s src
.............................................s............
----------------------------------------------------------------------
Ran 58 tests in 10.319s

OK (skipped=1)
py38 run-test: commands[1] | pylint -r no src/sphinxcontrib
************* Module sphinxcontrib.programoutput
src/sphinxcontrib/programoutput/__init__.py:188:8: R1732: Consider using 'with' for resource-allocating operations (consider-using-with)

------------------------------------------------------------------
Your code has been rated at 9.98/10 (previous run: 9.98/10, +0.00)

ERROR: InvocationError for command /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/py38/bin/pylint -r no src/sphinxcontrib (exited with code 8)
py39 create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/py39
SKIPPED: InterpreterNotFound: python3.9
pypy create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/pypy
SKIPPED: InterpreterNotFound: pypy
doc create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/doc
doc installdeps: pylint, coverage
doc develop-inst: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17
doc installed: alabaster==0.7.12,astroid==2.5.6,Babel==2.9.0,certifi==2020.12.5,chardet==4.0.0,coverage==5.5,docutils==0.16,idna==2.10,imagesize==1.2.0,isort==5.8.0,Jinja2==2.11.3,lazy-object-proxy==1.6.0,MarkupSafe==1.1.1,mccabe==0.6.1,packaging==20.9,Pygments==2.8.1,pylint==2.8.2,pyparsing==2.4.7,pytz==2021.1,requests==2.25.1,snowballstemmer==2.1.0,Sphinx==3.5.4,sphinxcontrib-applehelp==1.0.2,sphinxcontrib-devhelp==1.0.2,sphinxcontrib-htmlhelp==1.0.3,sphinxcontrib-jsmath==1.0.1,# Editable install with no version control (sphinxcontrib-programoutput==0.17),-e /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/src,sphinxcontrib-qthelp==1.0.3,sphinxcontrib-serializinghtml==1.1.4,toml==0.10.2,urllib3==1.26.4,wrapt==1.12.1
doc run-test-pre: PYTHONHASHSEED='2428015188'
doc run-test: commands[0] | sphinx-build -W -b linkcheck -d /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/doc/tmp/doctrees doc /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/doc/tmp/linkcheck
Running Sphinx v3.5.4
making output directory... done
loading intersphinx inventory from https://docs.python.org/objects.inv...
loading intersphinx inventory from http://packages.python.org/sphinxcontrib-ansi/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
intersphinx inventory has moved: http://packages.python.org/sphinxcontrib-ansi/objects.inv -> https://pythonhosted.org/sphinxcontrib-ansi/objects.inv
building [mo]: targets for 0 po files that are out of date
building [linkcheck]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index


(           index: line  192) ok        https://docs.python.org/3/library/shlex.html#shlex.split
(           index: line  123) ok        https://docs.python.org/3/library/shlex.html#module-shlex
(           index: line  246) ok        https://docs.python.org/2/library/string.html#formatstrings
(           index: line   11) redirect  http://www.sphinx-doc.org/en/stable/ - with Found to https://www.sphinx-doc.org/en/master/
(           index: line  166) ok        https://docs.python.org/3/library/sys.html#sys.exit
(           index: line  263) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues
(           index: line  275) ok        https://github.com/NextThought/sphinxcontrib-programoutput
(           index: line  285) redirect  http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html - permanently to https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
(           index: line   93) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues/17
(           index: line   63) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues/29
(           index: line   46) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues/33
(           index: line   71) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues/25
(           index: line   30) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues/38
(           index: line   79) ok        https://github.com/habnabit/sphinxcontrib-programoutput/commit/592078e0386c2a36d50a6528b6e49d91707138bf
(           index: line   57) ok        https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens
(           index: line   12) ok        https://github.com/NextThought/sphinxcontrib-programoutput/issues/50
(           index: line  282) redirect  https://gun.io/blog/how-to-github-fork-branch-and-pull-request/ - permanently to https://www.gun.io/blog/how-to-github-fork-branch-and-pull-request
(           index: line  288) ok        https://www.python.org/dev/peps/pep-0008
(           index: line  288) redirect  https://pypi.python.org/pypi/pep8/ - permanently to https://pypi.org/project/pep8/
(           index: line   21) ok        https://github.com/NextThought/sphinxcontrib-programoutput/pull/41
(           index: line  290) redirect  https://help.github.com/articles/using-pull-requests - permanently to https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
(           index: line   19) redirect  https://pypi.python.org/pypi/sphinxcontrib-programoutput - permanently to https://pypi.org/project/sphinxcontrib-programoutput/
build succeeded.

Look for any errors in the above output or in .tox/doc/tmp/linkcheck/output.txt
doc run-test: commands[1] | sphinx-build -W -b html -d /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/doc/tmp/doctrees doc /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/doc/tmp/html
Running Sphinx v3.5.4
making output directory... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] index

generating indices... genindex py-modindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in .tox/doc/tmp/html.
coverage create: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/coverage
coverage installdeps: pylint, coverage
coverage develop-inst: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17
coverage installed: alabaster==0.7.12,astroid==2.5.6,Babel==2.9.0,certifi==2020.12.5,chardet==4.0.0,coverage==5.5,docutils==0.16,idna==2.10,imagesize==1.2.0,isort==5.8.0,Jinja2==2.11.3,lazy-object-proxy==1.6.0,MarkupSafe==1.1.1,mccabe==0.6.1,packaging==20.9,Pygments==2.8.1,pylint==2.8.2,pyparsing==2.4.7,pytz==2021.1,requests==2.25.1,snowballstemmer==2.1.0,Sphinx==3.5.4,sphinxcontrib-applehelp==1.0.2,sphinxcontrib-devhelp==1.0.2,sphinxcontrib-htmlhelp==1.0.3,sphinxcontrib-jsmath==1.0.1,# Editable install with no version control (sphinxcontrib-programoutput==0.17),-e /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/src,sphinxcontrib-qthelp==1.0.3,sphinxcontrib-serializinghtml==1.1.4,toml==0.10.2,urllib3==1.26.4,wrapt==1.12.1
coverage run-test-pre: PYTHONHASHSEED='2428015188'
coverage run-test: commands[0] | coverage combine
coverage run-test: commands[1] | coverage html -i
coverage run-test: commands[2] | coverage report -i --fail-under=100
Name                                                      Stmts   Miss  Cover
-----------------------------------------------------------------------------
src/sphinxcontrib/programoutput/__init__.py                 141      2    99%
src/sphinxcontrib/programoutput/tests/__init__.py           111      2    98%
src/sphinxcontrib/programoutput/tests/test_cache.py          56      0   100%
src/sphinxcontrib/programoutput/tests/test_command.py        79      0   100%
src/sphinxcontrib/programoutput/tests/test_directive.py     217      2    99%
src/sphinxcontrib/programoutput/tests/test_setup.py           9      0   100%
src/sphinxcontrib/programoutput/tests/test_util.py           19      0   100%
-----------------------------------------------------------------------------
TOTAL                                                       632      6    99%
Coverage failure: total of 99 is less than fail-under=100
ERROR: InvocationError for command /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-programoutput-0.17/.tox/coverage/bin/coverage report -i --fail-under=100 (exited with code 2)
_________________________________________________________________________________ summary __________________________________________________________________________________
SKIPPED:  py27: InterpreterNotFound: python2.7
SKIPPED:  py27-old: InterpreterNotFound: python2.7
SKIPPED:  py36: InterpreterNotFound: python3.6
SKIPPED:  py37: InterpreterNotFound: python3.7
ERROR:   py38: commands failed
SKIPPED:  py39: InterpreterNotFound: python3.9
SKIPPED:  pypy: InterpreterNotFound: pypy
  doc: commands succeeded
ERROR:   coverage: commands failed

How to specify a python interpreter?

Sincerely thanks for your amazing tool.

Does programoutput use the default python interpreter?

How to specify a python interpreter?

Thank you very much : )

Uses literal `python` instead of sys.executable

On distros, using python will result in Python 2.7 being used, or if being installed into a docker image there will often be no python executable unless the python2 packages are installed, and .. 2020 is just around the corner.

Using sys.executable should fix that.

Drop support for old Pythons

If we still support them. This would be Python 2.6 and anything less than 3.4.

Consider adding the sphinx-extension GitHub topic

Just wanted to say you should consider adding the sphinx-extension topic, https://github.com/topics/sphinx-extension, to the repo so it is easier for others to find on the GitHub ecosystem. There are currently 96 other sphinx extensions that use that topic.

Consider migrating extension under sphinx-contrib

As we already seen Sphinx extensions getting affected by bitrot, or even dissapearing, it would be a wise move to move this extension under https://github.com/sphinx-contrib

For example I was able to recently resurrect the missing ansi extension that was used in the past by sphinxcontrib-programoutput to render ANSI escapes. The support was removed 4 years ago but we can now put it back as the extension is published on pypi and its code at https://github.com/sphinx-contrib/ansi

Move tests into program directory

If possible, weird use of a module in a namespace package may make this complicated.

100% test coverage

sphinxcontrib.programoutput extension does not declare if it is safe for parallel reading

Hey, glad to see this package being revived! We use programoutput for our Spack documentation and it's very useful.

When I build our documentation in parallel, I see the following warning message:

WARNING: the sphinxcontrib.programoutput extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit
WARNING: doing serial read

Is there any way to get programoutput to work in parallel? If not, can we explicitly declare that it doesn't support parallel reading to remove this warning message?

@svenevs may be interested in this conversation.

automock compatibility

I am in the same situation as readthedocs/readthedocs.org#5512: I want to run sphinx on readthedocs without having to install the entire 600MB of dependencies that my project needs.

I am using autodoc_mock_imports to avoid having to install my dependencies just for docs:

https://github.com/neuropoly/spinalcordtoolbox/blob/67a2bdb378344a4cef828b23ba7af0debd20b8d9/documentation/source/conf.py#L50

but I'm also using program-output:: and the mocks don't reach past it, so the build fails. Is there some special flag I can pass to python to get program-output:: to pick up the mocks too?

Like, can I do:

program-output:: SPHINX_AUTOMOCK=1 python -c my_tool.py -h

?

Plugin Broken with Sphinx 2+: Logging API

Hi there,

thanks for maintaining this useful plugin!

In Sphinx 2+ Sphinx object has no logging interface and

app.warn('Unexpected return code {0} from command {1}'.format(
         returncode, command))

in https://github.com/NextThought/sphinxcontrib-programoutput/blob/master/src/sphinxcontrib/programoutput/__init__.py#L223 fails.

The new approach is documented here https://www.sphinx-doc.org/en/master/extdev/logging.html

Best, M

Get rights to the pypi and readthedocs pages

I think it'd be worth it contacting @lunaryorn to get credentials/any more recent source so this repo can become canonical.

sphinxcontrib-programoutput and sphinx-autorun

Hey! I'm the maintainer for sphinx-autorun, and it seems that we've quite a bit overlap. (Your docs seem to be far more complete though!)

I'm wondering if you're willing to discuss merging both packages into one single project, to avoid both duplicating efforts.

Option to change command that appears at prompt

In my current use case I'm capturing the help output of a command within a project I'm documenting.

Something like so:

.. command-output:: python -m package.command --help

Which builds to:

$ python -m package.command --help

...

This works as expected, which is great. My problem however is that I really want to have the name of the setuputil's script entry-point appear at the prompt instead, as this is realistically how most users will invoke the command. It would be nice if an option could be added to modify/override the command that appears at the prompt.

Add version specific classifiers

Docs claim to support py 2.6, do we? What about py3.?