structured-tutorials 0.2.0__tar.gz → 0.4.0__tar.gz

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/.github/workflows/tests.yml

@@ -14,10 +14,16 @@ jobs:
       matrix:
         os: [ ubuntu-latest ]
         python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]
-        sphinx-version: [ "8.1", "8.2" ]
+        sphinx-version: [ "8.1", "8.2", "9.0", "9.1" ]
         exclude:
           - python-version: "3.10"
             sphinx-version: "8.2"
+          - python-version: "3.10"
+            sphinx-version: "9.0"
+          - python-version: "3.10"
+            sphinx-version: "9.1"
+          - python-version: "3.11"
+            sphinx-version: "9.1"
 
     name: Python ${{ matrix.python-version }}, Sphinx ${{ matrix.sphinx-version }}
     steps:

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/.gitignore

@@ -1,11 +1,16 @@
-# Python-generated files
-__pycache__/
+*.box
+*.egg-info
 *.py[oc]
+.config/
+.vagrant.d/
+.vagrant/
+/schema.json
+__pycache__/
 build/
 dist/
-wheels/
-*.egg-info
 tests/data/docs/_build/
+tests/data/tutorials/Vagrantfile
+wheels/
 
 # Virtual environments
 .venv

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/.readthedocs.yaml

@@ -18,13 +18,13 @@ build:
       - git fetch --all --tags || true
     create_environment:
       - asdf plugin add uv
-      - asdf install uv 0.9.2
-      - asdf global uv 0.9.2
+      - asdf install uv 0.9.27
+      - asdf global uv 0.9.27
     install:
-      - uv sync
+      - uv sync --group dev --group rtd
     pre_build:
       - ./fetch_swagger.sh
-      - uv run generate-schema.py
+      - uv run generate-schema.py -o > docs/_static/schema.json
     build:
       html:
         - uv run sphinx-build -T -b html docs/ $READTHEDOCS_OUTPUT/html

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structured-tutorials
-Version: 0.2.0
+Version: 0.4.0
 Summary: Add your description here
 Project-URL: Homepage, https://structured-tutorials.readthedocs.io/
 Project-URL: Documentation, https://structured-tutorials.readthedocs.io/
@@ -27,7 +27,7 @@ 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: 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'
@@ -44,8 +44,8 @@ Description-Content-Type: text/markdown
 `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
+With `structured-tutorials` you to specify steps (commands, files to create, ...) in a YAML file. A Sphinx
+plugin allows you to render them in your project documentation. A command-line tool can load the YAML file and
 run it on your local system.
 
 Please see the [official documentation](https://structured-tutorials.readthedocs.io/) for more detailed
@@ -68,7 +68,7 @@ extensions = [
 ]
 
 # Optional: Root directory for tutorials (default: location of conf.py)
-#structured_tutorials_root = DOC_ROOT / "tutorials"
+# structured_tutorials_root = DOC_ROOT / "tutorials"
 ```
 
 ## Your first (trivial) tutorial

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/README.md

@@ -9,8 +9,8 @@
 `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
+With `structured-tutorials` you to specify steps (commands, files to create, ...) in a YAML file. A Sphinx
+plugin allows you to render them in your project documentation. A command-line tool can load the YAML file and
 run it on your local system.
 
 Please see the [official documentation](https://structured-tutorials.readthedocs.io/) for more detailed
@@ -33,7 +33,7 @@ extensions = [
 ]
 
 # Optional: Root directory for tutorials (default: location of conf.py)
-#structured_tutorials_root = DOC_ROOT / "tutorials"
+# structured_tutorials_root = DOC_ROOT / "tutorials"
 ```
 
 ## Your first (trivial) tutorial

structured_tutorials-0.4.0/docs/changelog.rst

@@ -0,0 +1,65 @@
+#########
+ChangeLog
+#########
+
+******************
+0.4.0 (2026-04-04)
+******************
+
+* Added support for running tutorials in Vagrant.
+* Initial context variables are now rendered.
+* Alternatives now allow specific context and environment variables.
+* The JSON schema is now available `here <_static/schema.json>`_ and can be used in IDEs such as PyCharm.
+* Add ability to specify required executables that are checked before running a tutorial.
+* Rename ``tutorial_root`` to ``root``.
+* Alternatives can now be skipped in documentation.
+* Changing the working directory moved out of doc/run blocks as it is common functionality.
+* ``chdir`` can now be ``False`` to switch back to where the tutorial started.
+
+******************
+0.3.0 (2025-12-26)
+******************
+
+* Add support for Sphinx 9.0.
+* Tutorials can now be configured to pass a clear environment to all processes.
+* Tutorials can now configure additional environment variables passed to all processes.
+* Single commands can now update the environment for all subsequent commands. Values are rendered as
+  templates, so you can add (parts of) the output of a command to the environment by combining a test for
+  the command output that uses a named pattern in a regular expression for the output.
+* ``parts.{commands}.{command}.run.{chdir}`` is now a template. This allows you to change the directory based
+  on the output of a previous command.
+* Bugfix: Individual commands marked as skipped for documentation, are now actually skipped.
+
+******************
+0.2.0 (2025-12-23)
+******************
+
+Documentation
+=============
+
+* Continue reworking the documentation.
+* Add option to render extra text before/after a part. The text is rendered as a template.
+* Parts can now have an ID that you can reference when rendering parts to make sure that you render what
+  you actually think you render (useful for longer tutorials).
+* Add ``structured_tutorials_context`` option to pass extra context variables to a tutorial.
+* Rename the ``tutorial_root`` option to ``structured_tutorials_root``.
+* rename the ``structured_tutorial_command_text_width`` option to ``structured_tutorials_command_text_width``.
+
+Command-line
+============
+
+* Add option ``--define {key} {value}`` to pass extra context variables.
+* Greatly improve error handling.
+* Parts can now have a name that is shown before running a tutorial part.
+* Add option to clear the environment for a command.
+* Add option to add extra environment variables for a command. Environment variables are rendered as
+  templates.
+* Add ability to pass input to a process.
+* Command output can now also be tested for line or character count. You can specify an exact match, or a
+  minimum and/or maximum.
+
+******************
+0.1.0 (2025-12-22)
+******************
+
+Initial version.

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/docs/conf.py

@@ -1,5 +1,7 @@
 """Standard Sphinx configuration module."""
 
+from importlib.util import find_spec
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -18,12 +20,14 @@ release = "0.1.0"
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "sphinx_rtd_theme",
     "sphinxcontrib.spelling",
     "structured_tutorials.sphinx",
     "sphinx_inline_tabs",
 ]
-html_theme = "sphinx_rtd_theme"
+
+if find_spec("sphinx_rtd_theme") is not None:
+    extensions.append("sphinx_rtd_theme")
+    html_theme = "sphinx_rtd_theme"
 
 DOC_ROOT = Path(__file__).parent
 structured_tutorials_root = DOC_ROOT / "tutorials"

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/docs/how-tos.rst

@@ -28,15 +28,20 @@ This will render as:
 Running commands
 ****************
 
-Test the status code
-====================
+Test for installed tools
+========================
 
-``structured-tutorials`` will abort a tutorial if  a specified command does not exit with a status code of
-``0``. To check for a different status code, simply specify ``status_code``:
+You can specify a list of tools that is required for running the tutorial. ``structured-tutorials`` will then
+test if a certain tool is installed before starting the tutorial and present the user with a nice error
+message:
 
-.. literalinclude:: /tutorials/exit_code/tutorial.yaml
+.. literalinclude:: /tutorials/required_executables/tutorial.yaml
     :language: yaml
 
+.. structured-tutorial:: required_executables/tutorial.yaml
+
+.. structured-tutorial-part::
+
 Cleanup after running a tutorial
 ================================
 
@@ -65,7 +70,7 @@ run, in order, ``clean3``, ``clean1`` and ``clean2``. Should ``cmd1`` return a n
 Skip a part at runtime
 ======================
 
-To skip an entire part at runtime, but still show it in documentation, you can use the ``skip`` configuration:
+To skip an entire part at runtime, but still show it in documentation, simply set ``run: false``:
 
 .. literalinclude:: /tutorials/skip-part-run/tutorial.yaml
     :language: yaml

structured_tutorials-0.4.0/docs/howto/chdir.rst

@@ -0,0 +1,104 @@
+########################
+Change working directory
+########################
+
+Sometimes you will want to change the working directory where commands are run from. At runtime, this will
+change the meaning of relatives paths in commands, when rendering documentation, the prompt will show a
+different working directory.
+
+The working directory can changed using the ``chdir`` directive of commands. The value is a path, and is
+rendered as a template.
+
+*******
+Example
+*******
+
+Consider the following tutorial file:
+
+.. literalinclude:: /tutorials/chdir/tutorial.yaml
+    :language: yaml
+
+.. structured-tutorial:: chdir/tutorial.yaml
+
+The first commands part shows the user how to switch the working directory and run a command there:
+
+.. structured-tutorial-part::
+
+
+The second commands part shows the user how to create and switch to another directory, where the path is
+determined by a context variable:
+
+.. structured-tutorial-part::
+
+... but will run in a random directory at runtime.
+
+``chdir`` and alternatives
+==========================
+
+Changing the working directory is a bit more tricky with alternatives. At runtime, it is easy to follow the
+selected alternative and do whatever that alternative specifies. But when rendering documentation, *all*
+alternatives are rendered as tabs. Different alternatives might switch to different directories, so which
+directory should subsequent parts use?
+
+That's why a ``chdir`` directive in an alternative part is discarded after the part when rendering
+documentation. If all alternatives switch to the same directory, you can specify ``chdir`` also for the
+alternative. The following contrived example kind of shows how *not* to use this feature, but this better
+showcases how this works:
+
+.. literalinclude:: /tutorials/alternatives-chdir-at-top-level/tutorial.yaml
+    :language: yaml
+
+.. structured-tutorial:: alternatives-chdir-at-top-level/tutorial.yaml
+
+The first part renders two alternatives, in this case they even switch to different directories:
+
+.. structured-tutorial-part::
+
+But since the alternative specifies ``chdir: /alt``, the next part will use that as working directory:
+
+.. structured-tutorial-part::
+
+
+Switch back to the original working directory
+=============================================
+
+You can also switch back to the original working directory that you started from by setting ``chdir: false``:
+
+.. literalinclude:: /tutorials/chdir-false/tutorial.yaml
+    :language: yaml
+
+.. structured-tutorial:: chdir-false/tutorial.yaml
+
+As you can see, the third command is back in the home directory:
+
+.. structured-tutorial-part::
+
+Use a true temporary directory at runtime
+=========================================
+
+Since ``chdir`` is a template value and ``update_context`` and/or output tests (that may update the context)
+are run before applying it, the best way is simply use ``mkdir`` only at runtime:
+
+.. literalinclude:: /tutorials/chdir-with-mkdtemp/tutorial.yaml
+    :language: yaml
+
+.. structured-tutorial:: chdir-with-mkdtemp/tutorial.yaml
+
+This will show ``/tmp/docs`` in documentation:
+
+.. structured-tutorial-part::
+
+
+Switch to a different directory in documentation and at runtime
+===============================================================
+
+The best way to do this is to specify a different context for documentation and runtime. The above example
+already does this.
+
+Why do I have to specify ``chdir`` at runtime, even though my command already actually changes it?
+==================================================================================================
+
+Because the command you specify is launched in a subprocess, and the caller (structured-tutorials) has no idea
+what that subprocess does. Your command is still useful (it shows that switching directory will work), but
+there is no way to pass this information to the next command.
+

structured_tutorials-0.4.0/docs/howto/test-commands.rst

@@ -0,0 +1,67 @@
+#############
+Test commands
+#############
+
+When running commands, there are various ways to test if the command succeeded and ran as expected.
+
+You can also use tests to update the context for subsequent commands based on the output of a command.
+
+.. NOTE:: You can specify multiple tests as well (e.g. test the output *and* check if a port was opened).
+
+********************
+Test the status code
+********************
+
+``structured-tutorials`` will abort a tutorial if  a specified command does not exit with a status code of
+``0``. To check for a different status code, simply specify ``status_code``:
+
+.. literalinclude:: /tutorials/exit_code/tutorial.yaml
+    :language: yaml
+
+**************************
+Test output of the command
+**************************
+
+You can test either the standard output or standard error stream of a command with a regular expression. You
+can also test line and character count. Regular expressions with named patterns can be used to update the
+context for later commands:
+
+.. tab:: Configuration
+
+    .. literalinclude:: /tutorials/test-output/tutorial.yaml
+        :caption: docs/tutorials/test-output/tutorial.yaml
+        :language: yaml
+
+.. tab:: Documentation
+
+    .. structured-tutorial:: test-output/tutorial.yaml
+
+    .. structured-tutorial-part::
+
+
+******************
+Run a test command
+******************
+
+You can run a test command to verify that the command actually ran successfully:
+
+.. literalinclude:: /tutorials/test-command/tutorial.yaml
+    :caption: docs/tutorials/test-command/tutorial.yaml
+    :language: yaml
+
+Note that you can also retry commands, as shown for ports below.
+
+*********
+Test port
+*********
+
+You can test that a port is opened by the command:
+
+.. literalinclude:: /tutorials/test-port/tutorial.yaml
+    :caption: docs/tutorials/test-port/tutorial.yaml
+    :language: yaml
+
+For ports and commands, you can also specify a `retry` to run the test command multiple times before the main
+command is considered to have failed. A `delay` will delay the first run of the command and a
+`backoff_factor` will introduce an increasing delay between retries. A common use case is a daemon that
+will *eventually* open a port, but subsequent commands want to connect to that daemon.

structured_tutorials-0.4.0/docs/howto/vagrant.rst

@@ -0,0 +1,114 @@
+###########################
+Run a tutorial with Vagrant
+###########################
+
+You can use `Vagrant <https://developer.hashicorp.com/vagrant>`_ to run a tutorial inside one (or more)
+virtual machines. This approach is slow and resource intensive, but ensures maximum isolation and allows you
+to write and test tutorials that you would not want to run on the local system.
+
+***************
+Getting started
+***************
+
+Assuming you have Vagrant installed, getting started is very simple.
+
+First, let's write a trivial tutorial file and tell `structured-tutorials` to use the Vagrant runner:
+
+.. literalinclude:: /tutorials/vagrant-simple/tutorial.yaml
+    :caption: tutorial.yaml
+    :language: yaml
+
+Then, in same folder as your :file:`tutorial.yaml`, place a simple :file:`Vagrantfile`:
+
+.. literalinclude:: /tutorials/vagrant-simple/Vagrantfile
+    :caption: Vagrantfile
+
+.. structured-tutorial:: vagrant-simple/tutorial.yaml
+
+You can now run your tutorial in Vagrant:
+
+.. code-block:: console
+
+   user@host:~$ structured-tutorial tutorial.yaml
+
+Configure Vagrant environment
+=================================
+
+You can configure `environment variables used by Vagrant <https://developer.hashicorp
+.com/vagrant/docs/other/environmental-variables>`_ invocation by using the `environment` option.
+
+The most common example is to configure a different `VAGRANT_CWD <https://developer.hashicorp
+.com/vagrant/docs/other/environmental-variables>`_. The default is the same directory as your tutorial YAML
+file. For example, if you have the Vagrantfile in a subdirectory:
+
+.. literalinclude:: /tutorials/vagrant-subdir/tutorial.yaml
+    :caption: example/tutorial.yaml
+    :language: yaml
+
+.. literalinclude:: /tutorials/vagrant-subdir/subdir/Vagrantfile
+    :caption: example/subdir/Vagrantfile
+
+Use multiple VMs
+================
+
+Vagrant allows you to `define multiple VMs in a single Vagrantfile <https://developer.hashicorp
+.com/vagrant/docs/multi-machine>`_. `structured-tutorials` allows you to
+specify in which machine a particular part should run in via the `options` directive:
+
+.. literalinclude:: /tutorials/vagrant-machines/tutorial.yaml
+    :caption: tutorial.yaml
+    :language: yaml
+
+In this example the Vagrantfile specifies two VMs:
+
+.. literalinclude:: /tutorials/vagrant-machines/Vagrantfile
+    :caption: Vagrantfile
+
+.. structured-tutorial:: vagrant-machines/tutorial.yaml
+
+The first `commands` block will run in the `foo` VM:
+
+.. structured-tutorial-part::
+
+... while the second block will run in the `bar` VM:
+
+.. structured-tutorial-part::
+
+Prepare a custom base box
+=========================
+
+Sometimes you need to prepare a custom base box for the main tutorial. Known use cases are preparing a box
+that already has some tools installed or changing the VM so that it connects using a different user.
+
+The following tutorial is a contrived example showing a user how to set up PostgreSQL on a "db" host and
+Nginx on a "web" host. VMs are started from a custom-built "base" box that already has some common tools
+installed and allows SSH access as root:
+
+.. literalinclude:: /tutorials/vagrant-prepare-box/tutorial.yaml
+    :caption: tutorial.yaml
+    :language: yaml
+
+As per the `prepare_box` directive, we have to specify a Vagrantfile for the base box in the ``box/`` folder:
+
+.. literalinclude:: /tutorials/vagrant-prepare-box/box/Vagrantfile
+    :caption: box/Vagrantfile
+
+And the provisioning script in the same location:
+
+.. literalinclude:: /tutorials/vagrant-prepare-box/box/provision.sh
+    :caption: box/provision.sh
+
+And finally the main Vagrantfile specifying the `db` and `web` VMs from the tutorial configuration file:
+
+.. literalinclude:: /tutorials/vagrant-prepare-box/Vagrantfile
+    :caption: Vagrantfile
+
+.. structured-tutorial:: vagrant-prepare-box/tutorial.yaml
+
+The first `commands` block will run in the `web` VM:
+
+.. structured-tutorial-part::
+
+... while the second block will run in the `db` VM:
+
+.. structured-tutorial-part::

structured_tutorials-0.4.0/docs/index.rst

@@ -0,0 +1,30 @@
+structured-tutorials documentation
+==================================
+
+`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 (commands, files to create, ...) in a YAML file. A Sphinx
+plugin allows you to render them in your project documentation. A command-line tool can load the YAML file and
+run it on your local system.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   /quickstart
+   /how-tos
+   /reference
+   /changelog
+   /dev
+
+How-Tos
+-------
+
+.. toctree::
+   :maxdepth: 1
+   :caption: More specific How-Tos:
+
+   /howto/chdir
+   /howto/test-commands
+   /howto/vagrant

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/docs/quickstart.rst

@@ -27,6 +27,14 @@ To render your tutorials in Sphinx, add the extension and, optionally, where you
     # Location where your tutorials are stored (default: same directory as conf.py).
     #structured_tutorials_root = Path(__file__).parent / "tutorials"
 
+Editor integration
+==================
+
+The JSON schema is can be found `here <_static/schema.json>`_ and can be used in IDEs for auto-completion
+and validation. For example:
+
+* `PyCharm <https://www.jetbrains.com/help/pycharm/yaml.html#json_schema>`_
+
 
 *******************
 Your first tutorial
@@ -184,56 +192,9 @@ You can verify the success of commands by checking the status code, the output o
 opened properly. You can add multiple tests, and when testing the output, update the context for successive
 commands.
 
-For ports and commands, you can also specify a `retry` to run the test command multiple times before the main
-command is considered to have failed. A `delay` will delay the first run of the command and a
-`backoff_factor` will introduce an increasing delay between retries. A common use case is a daemon that
-will *eventually* open a port, but subsequent commands want to connect to that daemon.
-
-Test status code
-----------------
-
-By default, a non-zero status code is considered an error, but you can also require a non-zero status
-code:
-
-.. literalinclude:: /tutorials/exit_code/tutorial.yaml
-    :caption: docs/tutorials/exit_code/tutorial.yaml
-    :language: yaml
-
-Test output
------------
-
-You can test either the standard output or standard error stream of a command with a regular expression. You
-can also use named patterns to update the context for later commands:
-
-.. tab:: Configuration
-
-    .. literalinclude:: /tutorials/test-output/tutorial.yaml
-        :caption: docs/tutorials/test-output/tutorial.yaml
-        :language: yaml
-
-.. tab:: Documentation
-
-    .. structured-tutorial:: test-output/tutorial.yaml
-
-    .. structured-tutorial-part::
+See :doc:`/howto/test-commands` for more information.
 
-Run a test command
-------------------
 
-You can run a test command to verify that the command actually ran successfully:
-
-.. literalinclude:: /tutorials/test-command/tutorial.yaml
-    :caption: docs/tutorials/test-command/tutorial.yaml
-    :language: yaml
-
-Test port
----------
-
-You can test that a port is opened by the command:
-
-.. literalinclude:: /tutorials/test-port/tutorial.yaml
-    :caption: docs/tutorials/test-port/tutorial.yaml
-    :language: yaml
 
 Select alternatives
 ===================

{structured_tutorials-0.2.0 → structured_tutorials-0.4.0}/docs/spelling_wordlist.txt

@@ -7,3 +7,9 @@ hostname
 cwd
 backend
 reStructuredText
+bugfix
+executables
+Vagrantfile
+Nginx
+subdir
+Tos