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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structured-tutorials
-Version: 0.1.0
+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/
@@ -67,14 +67,14 @@ extensions = [
     "structured_tutorials.sphinx",
 ]
 
-# Optional: Root directory for tutorials
-#tutorial_root = DOC_ROOT / "tutorials"
+# 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
-`tutorial_root` in `conf.py`):
+`structured_tutorials_root` in `conf.py`):
 
 ```yaml
 parts:
@@ -107,6 +107,9 @@ Configure the tutorial that is being displayed - this will not show any output:
 ```
 
 ## TODO
+
+* Test file existence or something like that
+* Platform independent "echo" step (useful for debugging/testing)
 * Run in vagrant
 
 # License

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

@@ -32,14 +32,14 @@ extensions = [
     "structured_tutorials.sphinx",
 ]
 
-# Optional: Root directory for tutorials
-#tutorial_root = DOC_ROOT / "tutorials"
+# 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
-`tutorial_root` in `conf.py`):
+`structured_tutorials_root` in `conf.py`):
 
 ```yaml
 parts:
@@ -72,6 +72,9 @@ Configure the tutorial that is being displayed - this will not show any output:
 ```
 
 ## TODO
+
+* Test file existence or something like that
+* Platform independent "echo" step (useful for debugging/testing)
 * Run in vagrant
 
 # License

structured_tutorials-0.2.0/docs/changelog.rst

@@ -0,0 +1,37 @@
+#########
+ChangeLog
+#########
+
+******************
+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.1.0 → structured_tutorials-0.2.0}/docs/conf.py

@@ -26,7 +26,7 @@ extensions = [
 html_theme = "sphinx_rtd_theme"
 
 DOC_ROOT = Path(__file__).parent
-tutorial_root = DOC_ROOT / "tutorials"
+structured_tutorials_root = DOC_ROOT / "tutorials"
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

structured_tutorials-0.2.0/docs/include/quickstart-more-features.rst

@@ -0,0 +1,13 @@
+.. structured-tutorial:: templates/tutorial.yaml
+
+First, create a temporary directory:
+
+.. structured-tutorial-part:: create-directory
+
+Then create a JSON file in it:
+
+.. structured-tutorial-part:: create-file
+
+You can verify the contents of the file like this:
+
+.. structured-tutorial-part::

{structured_tutorials-0.1.0 → structured_tutorials-0.2.0}/docs/include/quickstart.rst

@@ -2,6 +2,4 @@ Configure the tutorial that is being displayed - this will not show any output:
 
 .. structured-tutorial:: quickstart/tutorial.yaml
 
-Render the first part:
-
 .. structured-tutorial-part::

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

@@ -6,10 +6,16 @@ Quickstart
 Installation
 ************
 
-To do: show how to install wheel once it exists.
+**structured-tutorials** is published on `PyPI <https://pypi.org/project/structured-tutorials/>`_ and
+thus can simply be installed via ``pip`` (or any other package management tool, such as
+`uv <https://docs.astral.sh/uv/>`_):
 
-To configure Sphinx, you need to add an extension and, optionally, the root directory where the tutorials are
-located:
+.. code-block:: console
+
+    $ pip install structured-tutorials
+
+To render your tutorials in Sphinx, add the extension and, optionally, where your tutorials are stored
+(this can be outside of the Sphinx root):
 
 .. code-block:: python
 
@@ -18,11 +24,8 @@ located:
         "structured_tutorials.sphinx",
     ]
 
-    DOC_ROOT = Path(__file__).parent
-
-    # configure the root directory where tutorials are located. Defaults to
-    # the Sphinx source directory.
-    tutorial_root = DOC_ROOT / "tutorials"
+    # Location where your tutorials are stored (default: same directory as conf.py).
+    #structured_tutorials_root = Path(__file__).parent / "tutorials"
 
 
 *******************
@@ -40,8 +43,12 @@ You can run this tutorial straight away:
 .. code-block:: console
 
     user@host:~/example/$ structured-tutorial docs/tutorials/quickstart/tutorial.yaml
+    Running part 0...
+    + structured-tutorial --help
     usage: structured-tutorial [-h] path
     ...
+    + echo "Finished running example tutorial."
+    Finished running example tutorial.
 
 Finally, you can render the tutorial in your Sphinx tutorial:
 
@@ -54,58 +61,63 @@ In fact, above lines are included below, so this is how this tutorial will rende
 .. include:: /include/quickstart.rst
 
 ***********************
-Tutorials are templates
+A more advanced example
 ***********************
 
-Commands as well as output are rendered using `Jinja <https://jinja.palletsprojects.com/en/stable/>`_
-templates. This allows you to reduce repetition of values or cases where a tutorial should behave differently
-from runtime when rendering documentation.
-
-The following example will create a directory, writes to a file in it and outputs the contents of said file:
-
-.. literalinclude:: /tutorials/templates/tutorial.yaml
-    :caption: docs/tutorials/templates/tutorial.yaml
-    :language: yaml
-
-This is how the documentation renders:
-
-.. structured-tutorial:: templates/tutorial.yaml
-
-.. structured-tutorial-part::
+The above is nice but not very useful. Let's show you a few new cool features next.
 
-However, when running, you will just get:
+Commands, output, file contents and many other parts are rendered using `Jinja templates
+<https://jinja.palletsprojects.com/en/stable/>`_. This allows you to reduce repetition of and use different
+values for documentation and runtime.
 
-.. code-block:: console
+Tutorials can create files (that are shown appropriately in your documentation). The tutorial below shows you
+how to create a JSON file that shows up with proper syntax highlighting.
 
-    user@host:~$ structured-tutorial docs/tutorials/templates/tutorial.yaml
-    real data
+You can test success of a command by checking the status code, output or even if a TCP port was
+opened. When checking the output, you can use regular expressions for matching and even named patterns to
+update the context with runtime data. Below we create a temporary directory with ``mktemp`` and use it
+later to create the file in it.
 
-***************************
-Tutorials can contain files
-***************************
+The following example will create a directory, writes to a file in it and outputs its contents:
 
-Tutorials can contain files that are also rendered as templates.
+.. literalinclude:: /tutorials/templates/tutorial.yaml
+    :caption: docs/tutorials/templates/tutorial.yaml
+    :language: yaml
 
-The following example tutorial could be used to instruct the user to create a JSON file in
-``/tmp/example.json`` and then call ``python`` to verify the syntax.
+Render this tutorial
+====================
 
-Using this YAML file:
+The code in your reStructuredText doesn't look much different. You render three parts, and the first two
+reference the id you have given them in the YAML file.
 
-.. literalinclude:: /tutorials/simple-file/tutorial.yaml
-    :caption: docs/tutorials/simple-file/tutorial.yaml
-    :language: yaml
+.. literalinclude:: /include/quickstart-more-features.rst
+    :caption: docs/tutorial.rst
+    :language: rst
 
-you could render a Tutorial like this:
+The above file is included below.
 
-.. structured-tutorial:: simple-file/tutorial.yaml
+.. include:: /include/quickstart-more-features.rst
 
-Create a configuration file with the following contents:
+Run this tutorial
+=================
 
-.. structured-tutorial-part::
+When running this tutorial, it'll do what you instructed the user to do: Create a temporary directory, then a
+JSON file in it, and then output it. Cleanup is assured through the cleanup directive, even if one of the
+commands would fail:
 
-and make sure it is valid JSON:
+.. code-block:: console
 
-.. structured-tutorial-part::
+    user@host:~/example/$ structured-tutorial docs/tutorials/templates/tutorial.yaml
+    Running part create-directory...
+    + mktemp -d
+    Running part create-file...
+    Running part 2...
+    + cat /tmp/tmp.6G6S9dX0MN/example.txt
+    {"key": "run"}
+    + cat /tmp/tmp.6G6S9dX0MN/example.txt | python -m json.tool
+    ...
+    INFO     | Running cleanup commands.
+    + rm -r /tmp/tmp.6G6S9dX0M
 
 ********************************************
 Generating documentation out of the tutorial

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

@@ -6,3 +6,4 @@ sudo
 hostname
 cwd
 backend
+reStructuredText

{structured_tutorials-0.1.0 → structured_tutorials-0.2.0}/docs/tutorials/quickstart/tutorial.yaml

@@ -5,4 +5,6 @@ parts:
           output: |
             usage: structured-tutorial [-h] path
             ...
-      - command: ls
+      - command: echo "Finished running example tutorial."
+    doc:
+      text_before: "This shows your first tutorial:"

structured_tutorials-0.2.0/docs/tutorials/templates/tutorial.yaml

@@ -0,0 +1,39 @@
+configuration:
+  context:  # context shared between documentation and runtime
+    filename: example.json
+  doc:  # template context at runtime
+    context:
+      dest: /tmp/tmp...
+      contents: '{"key": "doc"}'
+  run:  # template context at runtime
+    context:
+      # dest is captured and added to the context by mktemp at runtime
+      contents: '{"key": "run"}'
+parts:
+  - id: create-directory
+    commands:
+      - command: mktemp -d
+        doc:
+          output: "{{ dest }}"
+        run:
+          show_output: false
+          test:
+            # Capture the whole output and add it to the context
+            - regex: (?P<dest>.*)
+          cleanup:
+            # Remove temporary directory after running the tutorial
+            - command: rm -rf {{ dest }}
+  - id: create-file
+    contents: "{{ contents }}\n"
+    destination: "{{ dest }}/{{ filename }}"
+    doc:
+      language: json
+      # If you use sphinxcontrib-spelling, make sure the filename is not spell-checked
+      ignore_spelling: true
+  - commands:
+      - command: cat {{ dest }}/{{ filename }}
+        doc:
+          output: "{{ contents }}"
+      - command: cat {{ dest }}/{{ filename }} | python -m json.tool
+        doc:
+          output: ...