🧪 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`.
Raw data
{
"_id": null,
"home_page": "https://github.com/tillahoffmann/sphinxcontrib-shtest",
"name": "sphinxcontrib-shtest",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/c0/f0/6a4deed6434d9fc80ed33069b51895cfb9ac1eb2d3f578493beb3645360f/sphinxcontrib-shtest-0.5.0.tar.gz",
"platform": null,
"description": "\ud83e\uddea shtest\n=========\n\n.. image:: https://github.com/tillahoffmann/sphinxcontrib-shtest/actions/workflows/main.yaml/badge.svg\n :target: https://github.com/tillahoffmann/sphinxcontrib-shtest/\n.. image:: https://img.shields.io/pypi/v/sphinxcontrib-shtest\n :target: https://pypi.org/project/sphinxcontrib-shtest/\n\nshtest 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:\n\n- :code:`:returncode: [integer]` specifies the expected return code (defaults to 0).\n- adding the :code:`:stderr:` flag compares results with the :code:`stderr` rather than :code:`stdout` stream.\n- :code:`:cwd: [relative path]` specifies the working directory relative to the source of the document (defaults to the directory containing the source document).\n- :code:`:tempdir:` executes the test in a temporary directory.\n\nExamples\n--------\n\n.. code-block::\n\n\n # Obligatory hello world example.\n $ echo hello world\n hello world\n\n.. code-block::\n\n :stderr:\n\n # Read from stderr instead of stdout.\n $ echo message on stderr >&2\n message on stderr\n\n.. code-block::\n\n :returncode: 1\n\n # Use a non-zero expected return code.\n $ false\n\n.. code-block::\n\n\n # Run multiple tests in one directive.\n $ echo hello\n hello\n $ echo world\n world\n\n.. code-block::\n\n :cwd: tests\n\n # Run a test in a particular working directory relative to the document.\n $ cat hello.txt\n world\n\n.. code-block::\n\n :tempdir:\n\n # Run a test in a temporary directory.\n $ echo hello > world.txt\n\n.. ls -l\n\nInstallation\n------------\n\nRun :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`.\n",
"bugtrack_url": null,
"license": "",
"summary": "",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/tillahoffmann/sphinxcontrib-shtest"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c0f06a4deed6434d9fc80ed33069b51895cfb9ac1eb2d3f578493beb3645360f",
"md5": "fed2d1359e123274fafede3d79b2fe16",
"sha256": "65753c0ae0869ccfac53218cb491a253cd3965e730b74496c65c8938975cfafc"
},
"downloads": -1,
"filename": "sphinxcontrib-shtest-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "fed2d1359e123274fafede3d79b2fe16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5313,
"upload_time": "2023-05-18T18:53:35",
"upload_time_iso_8601": "2023-05-18T18:53:35.560477Z",
"url": "https://files.pythonhosted.org/packages/c0/f0/6a4deed6434d9fc80ed33069b51895cfb9ac1eb2d3f578493beb3645360f/sphinxcontrib-shtest-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-18 18:53:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tillahoffmann",
"github_project": "sphinxcontrib-shtest",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sphinxcontrib-shtest"
}
JSON
