Metadata-Version: 2.4
Name: structured-tutorials
Version: 0.2.0
Summary: Add your description here
Project-URL: Homepage, https://structured-tutorials.readthedocs.io/
Project-URL: Documentation, https://structured-tutorials.readthedocs.io/
Project-URL: Source, https://github.com/mathiasertl/structured-tutorials
Project-URL: Issues, https://github.com/mathiasertl/structured-tutorials/issues
Project-URL: Changelog, https://structured-tutorials.readthedocs.io/en/latest/changelog.html
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation :: Sphinx
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: colorama>=0.4.6
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic>=2.11.4
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: sphinx-inline-tabs>=2025
Requires-Dist: sphinx>=8.2.0; python_version >= '3.11'
Requires-Dist: sphinx~=8.1.0; python_version < '3.11'
Requires-Dist: termcolor>=3.2.0
Requires-Dist: typing-extensions>=4.6.0; python_version < '3.11'
Description-Content-Type: text/markdown

# structured-tutorials

![image](https://github.com/mathiasertl/structured-tutorials/workflows/Tests/badge.svg)
![image](https://img.shields.io/pypi/v/structured-tutorials.svg)
![image](https://img.shields.io/pypi/dm/structured-tutorials.svg)
![image](https://img.shields.io/pypi/pyversions/structured-tutorials.svg)
![image](https://img.shields.io/github/license/mathiasertl/structured-tutorials)

`structured-tutorials` allows you to write tutorials that can be rendered as documentation and run on your
system to verify correctness.

With `structured-tutorials` you to specify steps in a configuration file. A Sphinx plugin allows you to
render those commands in your project documentation. A command-line tool can load the configuration file and
run it on your local system.

Please see the [official documentation](https://structured-tutorials.readthedocs.io/) for more detailed
information.

## Installation / Setup

Install `structured-tutorials`:

```
pip install structured-tutorials
```

and configure Sphinx:

```python
extensions = [
    # ... other extensions
    "structured_tutorials.sphinx",
]

# Optional: Root directory for tutorials (default: location of conf.py)
#structured_tutorials_root = DOC_ROOT / "tutorials"
```

## Your first (trivial) tutorial

To create your first tutorial, create it in `docs/tutorial.yaml` (or elsewhere, if you configured
`structured_tutorials_root` in `conf.py`):

```yaml
parts:
  - commands:
      - command: structured-tutorial --help
        doc:
          output: |
            usage: structured-tutorial [-h] path
            ...
```

### Run the tutorial

Run the tutorial with:

```
$ structured-tutorial docs/tutorials/quickstart/tutorial.yaml
usage: structured-tutorial [-h] path
...
```

### Render tutorial in Sphinx:

Configure the tutorial that is being displayed - this will not show any output:

```
.. structured-tutorial:: quickstart/tutorial.yaml

.. structured-tutorial-part::
```

## TODO

* Test file existence or something like that
* Platform independent "echo" step (useful for debugging/testing)
* Run in vagrant

# License

This project is licensed under the MIT License. See LICENSE file for details.