{"id":16536277,"url":"https://github.com/tillahoffmann/sphinxcontrib-shtest","last_synced_at":"2025-06-15T14:02:53.779Z","repository":{"id":151054826,"uuid":"623707340","full_name":"tillahoffmann/sphinxcontrib-shtest","owner":"tillahoffmann","description":"Doctests for shell commands.","archived":false,"fork":false,"pushed_at":"2024-11-19T23:24:39.000Z","size":28,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T23:04:08.027Z","etag":null,"topics":["doctest","shell","sphinx-extension"],"latest_commit_sha":null,"homepage":"https://sphinxcontrib-shtest.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tillahoffmann.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-04-04T23:13:43.000Z","updated_at":"2024-11-19T23:24:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"1f889a91-59b5-43c2-b6e5-4c4d4d96fec0","html_url":"https://github.com/tillahoffmann/sphinxcontrib-shtest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillahoffmann%2Fsphinxcontrib-shtest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillahoffmann%2Fsphinxcontrib-shtest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillahoffmann%2Fsphinxcontrib-shtest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tillahoffmann%2Fsphinxcontrib-shtest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tillahoffmann","download_url":"https://codeload.github.com/tillahoffmann/sphinxcontrib-shtest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312141,"owners_count":21082638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["doctest","shell","sphinx-extension"],"created_at":"2024-10-11T18:30:15.756Z","updated_at":"2025-04-10T23:04:14.621Z","avatar_url":"https://github.com/tillahoffmann.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"🧪 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.. image:: https://readthedocs.org/projects/sphinxcontrib-shtest/badge/?version=latest\n    :target: https://sphinxcontrib-shtest.readthedocs.io/en/latest/?badge=latest\n\n:code:`shtest` tests shell commands in your Sphinx documentation.\n\nThe :code:`shtest` directive supports the usual `doctest \u003chttps://www.sphinx-doc.org/en/master/usage/extensions/doctest.html\u003e`_ syntax. The following example renders as shown below during a normal documentation build and runs the test when executed using the :code:`shtest` builder (see `Installation and Usage`_ for details).\n\n.. code-block:: rst\n\n    .. shtest::\n\n        # Obligatory hello world example.\n        $ echo hello world\n        hello world\n\n.. shtest::\n\n    # Obligatory hello world example.\n    $ echo hello world\n    hello world\n\nThe directive 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\nInstallation and Usage\n----------------------\n\n1. Run :code:`pip install sphinxcontrib-shtest` to install the package.\n2. Add :code:`\"sphinxcontrib.shtest\"` to your :code:`extensions` list in :code:`conf.py` to enable the extension (see `here \u003chttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions\u003e`__ for details).\n3. Execute :code:`sphinx-build -b shtest /path/to/source/directory /path/to/output/directory`. The :code:`-b shtest` flag executes the shell tests; run without the :code:`-b shtest` flag to build your documentation as usual.\n\nExamples\n--------\n\n.. code-block:: rst\n\n    .. shtest::\n        :stderr:\n\n        # Read from stderr instead of stdout.\n        $ echo message on stderr \u003e\u00262\n        message on stderr\n\n.. shtest::\n    :stderr:\n\n    # Read from stderr instead of stdout.\n    $ echo message on stderr \u003e\u00262\n    message on stderr\n\n.. code-block:: rst\n\n    .. shtest::\n        :returncode: 1\n\n        # Use a non-zero expected return code.\n        $ false\n\n.. shtest::\n    :returncode: 1\n\n    # Use a non-zero expected return code.\n    $ false\n\n.. code-block:: rst\n\n    .. shtest::\n\n        # Run multiple tests in one directive.\n        $ echo hello\n        hello\n        $ echo world\n        world\n\n.. shtest::\n\n    # Run multiple tests in one directive.\n    $ echo hello\n    hello\n    $ echo world\n    world\n\n.. code-block:: rst\n\n    .. shtest::\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.. shtest::\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:: rst\n\n    .. shtest::\n        :tempdir:\n\n        # Run a test in a temporary directory.\n        $ echo hello \u003e world.txt\n\n.. shtest::\n    :tempdir:\n\n    # Run a test in a temporary directory.\n    $ echo hello \u003e world.txt\n\n.. code-block:: rst\n\n    .. sh:: ls -l\n\n.. sh:: ls -l\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftillahoffmann%2Fsphinxcontrib-shtest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftillahoffmann%2Fsphinxcontrib-shtest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftillahoffmann%2Fsphinxcontrib-shtest/lists"}