Metadata-Version: 2.1
Name: sphinxcontrib-shtest
Version: 0.4.0
Home-page: https://github.com/tillahoffmann/sphinxcontrib-shtest
Description-Content-Type: text/x-rst

🧪 shtest
=========

.. image:: https://github.com/tillahoffmann/sphinxcontrib-shtest/actions/workflows/main.yaml/badge.svg
    :target: https://github.com/tillahoffmann/sphinxcontrib-shtest/
.. image:: https://img.shields.io/pypi/v/sphinxcontrib-shtest
    :target: https://pypi.org/project/sphinxcontrib-shtest/

shtest tests shell commands in your Sphinx documentation. The :code:`shtest` directive supports the usual `doctest <https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html>`_ syntax. It offers the following options:

- :code:`:returncode: [integer]` specifies the expected return code (defaults to 0).
- adding the :code:`:stderr:` flag compares results with the :code:`stderr` rather than :code:`stdout` stream.
- :code:`:cwd: [relative path]` specifies the working directory relative to the source of the document (defaults to the directory containing the source document).
- :code:`:tempdir:` executes the test in a temporary directory.

Examples
--------

.. code-block::


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

.. code-block::

    :stderr:

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

.. code-block::

    :returncode: 1

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

.. code-block::


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

.. code-block::

    :cwd: tests

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

.. code-block::

    :tempdir:

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

.. ls -l

Installation
------------

Run :code:`pip install sphinxcontrib-shtest` to install the package and add :code:`"sphinxcontrib-shtest"` to your :code:`extensions` list in :code:`conf.py` (see `here <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions>`__ for details). Then execute :code:`sphinx-build -b shtest /path/to/source/directory /path/to/output/directory`.
