/sphinxcontrib-shtest

Doctests for shell commands.

Primary LanguagePython

🧪 shtest

https://img.shields.io/pypi/v/sphinxcontrib-shtest https://readthedocs.org/projects/sphinxcontrib-shtest/badge/?version=latest

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
.. shtest::

    # 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
.. shtest::
    :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
.. shtest::
    :returncode: 1

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


.. shtest::

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

    # 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
.. shtest::
    :cwd: tests

    # 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
.. shtest::
    :tempdir:

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


.. sh:: ls -l
.. sh:: ls -l