🧪 shtest

shtest tests shell commands in your Sphinx documentation.

The shtest directive supports the usual doctest syntax. The following example renders as shown below during a normal documentation build and runs the test when executed using the shtest builder (see Installation and Usage for details).

.. shtest::

    # Obligatory hello world example.
    $ echo hello world
    hello world

# Obligatory hello world example.
$ echo hello world
hello world

The directive offers the following options:

• :returncode: [integer] specifies the expected return code (defaults to 0).

• adding the :stderr: flag compares results with the stderr rather than stdout stream.

• :cwd: [relative path] specifies the working directory relative to the source of the document (defaults to the directory containing the source document).

• :tempdir: executes the test in a temporary directory.

Installation and Usage

1. Run pip install sphinxcontrib-shtest to install the package.

2. Add "sphinxcontrib.shtest" to your extensions list in conf.py to enable the extension (see here for details).

3. Execute sphinx-build -b shtest /path/to/source/directory /path/to/output/directory. The -b shtest flag executes the shell tests; run without the -b shtest flag to build your documentation as usual.

Examples

.. shtest::
    :stderr:

    # Read from stderr instead of stdout.
    $ echo message on stderr >&2
    message on stderr

# Read from stderr instead of stdout.
$ echo message on stderr >&2
message on stderr

.. shtest::
    :returncode: 1

    # Use a non-zero expected return code.
    $ false

# Use a non-zero expected return code.
$ false

.. shtest::

    # Run multiple tests in one directive.
    $ echo hello
    hello
    $ echo world
    world

# Run multiple tests in one directive.
$ echo hello
hello
$ echo world
world

.. shtest::
    :cwd: tests

    # Run a test in a particular working directory relative to the document.
    $ cat hello.txt
    world

# Run a test in a particular working directory relative to the document.
$ cat hello.txt
world

.. shtest::
    :tempdir:

    # Run a test in a temporary directory.
    $ echo hello > world.txt

# Run a test in a temporary directory.
$ echo hello > world.txt

.. sh:: ls -l

$ ls -l
total 52
-rw-r--r-- 1 docs docs 3531 Apr 17 16:27 README.rst
drwxr-xr-x 3 docs docs 4096 Apr 17 16:27 _build
drwxr-xr-x 4 docs docs 4096 Apr 17 16:27 _readthedocs
-rw-r--r-- 1 docs docs 5657 Apr 17 16:27 conf.py
lrwxrwxrwx 1 docs docs   10 Apr 17 16:27 index.rst -> README.rst
-rw-r--r-- 1 docs docs  880 Apr 17 16:27 recipe.py
-rw-r--r-- 1 docs docs   71 Apr 17 16:27 requirements.in
-rw-r--r-- 1 docs docs 2702 Apr 17 16:27 requirements.txt
-rw-r--r-- 1 docs docs   31 Apr 17 16:27 setup.cfg
-rw-r--r-- 1 docs docs  542 Apr 17 16:27 setup.py
drwxr-xr-x 3 docs docs 4096 Apr 17 16:27 sphinxcontrib
drwxr-xr-x 2 docs docs 4096 Apr 17 16:27 sphinxcontrib_shtest.egg-info
drwxr-xr-x 3 docs docs 4096 Apr 17 16:27 tests