allow rendering of text before/after a specific part

mathiasertl · mathiasertl · commit 943d57627388 · 2025-12-22T22:56:01.000+01:00
diff --git a/README.md b/README.md
@@ -73,12 +73,6 @@ Configure the tutorial that is being displayed - this will not show any output:
 
 ## TODO
 
-* Running commands:
-
-  * Clear env
-  * Add env (value is template)
-
-* Pre/post text for each part
 * Test file existence or something like that
 * Platform independent "echo" step (useful for debugging/testing)
 * Run in vagrant
diff --git a/structured_tutorials/models/base.py b/structured_tutorials/models/base.py
@@ -67,6 +67,13 @@ class ConfigurationMixin:
     update_context: dict[str, Any] = Field(default_factory=dict)
 
 
+class DocumentationConfigurationMixin:
+    """Mixin for documentation configuration models."""
+
+    text_before: str = Field(default="", description="Text before documenting this part.")
+    text_after: str = Field(default="", description="Text after documenting this part.")
+
+
 class FileMixin:
     """Mixin for specifying a file (used in file part and for stdin of commands)."""
 
diff --git a/structured_tutorials/models/parts.py b/structured_tutorials/models/parts.py
@@ -14,6 +14,7 @@
     CommandBaseModel,
     CommandType,
     ConfigurationMixin,
+    DocumentationConfigurationMixin,
     FileMixin,
     template_field_title_generator,
 )
@@ -100,7 +101,7 @@ class CommandsRuntimeConfigurationModel(ConfigurationMixin, BaseModel):
     model_config = ConfigDict(extra="forbid")
 
 
-class CommandsDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+class CommandsDocumentationConfigurationModel(ConfigurationMixin, DocumentationConfigurationMixin, BaseModel):
     """Documentation configuration for an entire commands part."""
 
     model_config = ConfigDict(extra="forbid")
@@ -124,7 +125,7 @@ class FileRuntimeConfigurationModel(ConfigurationMixin, BaseModel):
     model_config = ConfigDict(extra="forbid", title="File part runtime configuration")
 
 
-class FileDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+class FileDocumentationConfigurationModel(ConfigurationMixin, DocumentationConfigurationMixin, BaseModel):
     """Configure a file part when rendering it as documentation.
 
     For the `language`, `caption`, `linenos`, `lineno_start`, `emphasize_lines` and `name` options, please
@@ -203,7 +204,9 @@ class AlternativeRuntimeConfigurationModel(ConfigurationMixin, BaseModel):
     model_config = ConfigDict(extra="forbid", title="File part runtime configuration")
 
 
-class AlternativeDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+class AlternativeDocumentationConfigurationModel(
+    ConfigurationMixin, DocumentationConfigurationMixin, BaseModel
+):
     """Configure an alternative part when documenting the tutorial."""
 
     model_config = ConfigDict(extra="forbid", title="File part runtime configuration")
diff --git a/structured_tutorials/sphinx/utils.py b/structured_tutorials/sphinx/utils.py
@@ -114,11 +114,15 @@ def render_code_block(self, part: CommandsPartModel) -> str:
             # Update the context from update_context
             self.context.update(command_config.doc.update_context)
 
-        template = """.. code-block:: console
-
-{% for cmd in commands %}{{ cmd|indent(4, first=True) }}
-{% endfor %}"""
-        return self.env.from_string(template).render({"commands": commands})
+        template_str = TEMPLATE_DIR.joinpath("commands_part.rst.template").read_text("utf-8")
+        template = self.env.from_string(template_str)
+        return template.render(
+            {
+                "commands": commands,
+                "text_after": self.render(part.doc.text_after),
+                "text_before": self.render(part.doc.text_before),
+            }
+        )
 
     def render_file(self, part: FilePartModel) -> str:
         content = part.contents
@@ -155,7 +159,15 @@ def render_file(self, part: FilePartModel) -> str:
 
         # Render template
         template = self.env.from_string(template_str)
-        value = template.render({"part": part, "content": content, "caption": caption})
+        value = template.render(
+            {
+                "part": part,
+                "content": content,
+                "caption": caption,
+                "text_after": self.render(part.doc.text_after),
+                "text_before": self.render(part.doc.text_before),
+            }
+        )
         return value
 
     def render_alternatives(self, part: AlternativeModel) -> str:
@@ -175,7 +187,14 @@ def render_alternatives(self, part: AlternativeModel) -> str:
 
         # Render template
         template = self.env.from_string(template_str)
-        value = template.render({"part": part, "tabs": tabs})
+        value = template.render(
+            {
+                "part": part,
+                "tabs": tabs,
+                "text_after": self.render(part.doc.text_after),
+                "text_before": self.render(part.doc.text_before),
+            }
+        )
         return value.strip()
 
     def render_part(self, part_id: str | None = None) -> str:
diff --git a/structured_tutorials/templates/alternative_part.rst.template b/structured_tutorials/templates/alternative_part.rst.template
@@ -1,5 +1,9 @@
+{% if text_before %}{{ text_before }}
+
+{% endif -%}
 {% for title, contents in tabs %}
 .. tab:: {{ title }}
 
     {{ contents|indent() }}
-{% endfor %}
+{% endfor %}
+{% if text_after %}{{ text_after }}{% endif %}
diff --git a/structured_tutorials/templates/commands_part.rst.template b/structured_tutorials/templates/commands_part.rst.template
@@ -0,0 +1,9 @@
+{% if text_before %}{{ text_before }}
+
+{% endif -%}
+.. code-block:: console
+
+{% for cmd in commands %}{{ cmd|indent(4, first=True) }}
+{% endfor %}{% if text_after %}
+
+{{ text_after }}{% endif %}
diff --git a/structured_tutorials/templates/file_part.rst.template b/structured_tutorials/templates/file_part.rst.template
@@ -1,8 +1,13 @@
+{% if text_before %}{{ text_before }}
+
+{% endif -%}
 .. code-block::{% if part.doc.language %} {{ part.doc.language }}{% endif %}{% if caption %}
     :caption: {{ caption }}{% endif %}{% if part.doc.linenos or part.doc.lineno_start %}
     :linenos:{% endif %}{% if part.doc.lineno_start %}
     :lineno-start: {{ part.doc.lineno_start }}{% endif %}{% if part.doc.emphasize_lines %}
     :emphasize-lines: {{ part.doc.emphasize_lines }}{% endif %}{% if part.doc.name %}
     :name: {{ part.doc.name }}{% endif %}
 
-    {{ content|indent() }}
+    {{ content|indent() }}{% if text_after %}
+
+{{ text_after }}{% endif %}
diff --git a/tests/data/tutorials/alternatives-text.yaml b/tests/data/tutorials/alternatives-text.yaml
@@ -0,0 +1,32 @@
+# alternatives with text before/after
+configuration:
+  context:
+    key: value
+parts:
+  - alternatives:
+      foo:
+        commands:
+          - command: ls foo
+      bar:
+        commands:
+          - command: ls bar
+    doc:
+      text_after: "after: {{ key }}"
+      text_before: "before: {{ key }}"
+  - alternatives:
+      foo:
+        commands:
+          - command: ls foo
+        doc:
+          text_after: "foo-after: {{ key }}"
+          text_before: "foo-before: {{ key }}"
+
+      bar:
+        commands:
+          - command: ls bar
+        doc:
+          text_after: "foo-after: {{ key }}"
+          text_before: "foo-before: {{ key }}"
+    doc:
+      text_after: "after2: {{ key }}"
+      text_before: "before2: {{ key }}"
diff --git a/tests/data/tutorials/command-text.yaml b/tests/data/tutorials/command-text.yaml
@@ -0,0 +1,10 @@
+# commands with text before/after
+configuration:
+  context:
+    key: value
+parts:
+  - commands:
+      - command: ls
+    doc:
+      text_after: "after: {{ key }}"
+      text_before: "before: {{ key }}"
diff --git a/tests/data/tutorials/file-contents-text.yaml b/tests/data/tutorials/file-contents-text.yaml
@@ -0,0 +1,10 @@
+# file with text before/after
+configuration:
+  context:
+    key: value
+parts:
+  - contents: foo
+    destination: "test.txt"
+    doc:
+      text_after: "after: {{ key }}"
+      text_before: "before: {{ key }}"
diff --git a/tests/runners/local/test_command.py b/tests/runners/local/test_command.py
@@ -174,7 +174,7 @@ def test_environment(fp: FakeProcess, runner: LocalTutorialRunner) -> None:
     recorder1 = fp.register("echo 1 $VARIABLE")
     recorder2 = fp.register("echo 2 $VARIABLE")
     runner.run()
-    assert recorder1.calls[0].kwargs["env"]["VARIABLE"] == "VALUE 1"
+    assert recorder1.calls[0].kwargs["env"]["VARIABLE"] == "VALUE 1"  # type: ignore[index]
     assert recorder2.calls[0].kwargs == {
         "shell": True,
         "stdin": None,
diff --git a/tests/runners/local/test_file.py b/tests/runners/local/test_file.py
@@ -0,0 +1,82 @@
+# Copyright (c) 2025 Mathias Ertl
+# Licensed under the MIT License. See LICENSE file for details.
+
+"""Tests for file parts."""
+
+from pathlib import Path
+
+import pytest
+
+from structured_tutorials.errors import RunTutorialException
+from structured_tutorials.models import FilePartModel, TutorialModel
+from structured_tutorials.runners.local import LocalTutorialRunner
+
+
+@pytest.mark.doc_tutorial("file-copy")
+def test_file_copy(tmp_path: Path, doc_tutorial: TutorialModel) -> None:
+    """Test skipping a part when running."""
+    # Update destination to copy to tmp_path
+    for part in doc_tutorial.parts:
+        assert isinstance(part, FilePartModel)
+        part.destination = str(tmp_path) + part.destination
+    runner = LocalTutorialRunner(doc_tutorial, interactive=False)
+    runner.run()
+
+    part = doc_tutorial.parts[0]
+    assert isinstance(part, FilePartModel)
+    assert Path(part.destination).exists()
+    with open(part.destination) as stream:
+        assert stream.read() == "inline contents: at runtime"
+
+    part = doc_tutorial.parts[1]
+    assert isinstance(part, FilePartModel)
+    assert Path(part.destination).exists()
+    with open(part.destination) as stream:
+        assert stream.read() == "inline contents: {{ variable }}"
+
+    part = doc_tutorial.parts[2]
+    assert isinstance(part, FilePartModel)
+    assert Path(part.destination).exists()
+    with open(part.destination) as stream:
+        assert stream.read() == "test: at runtime"
+
+    part = doc_tutorial.parts[3]
+    assert isinstance(part, FilePartModel)
+    assert Path(part.destination).exists()
+    with open(part.destination) as stream:
+        assert stream.read() == "test: {{ variable }}"
+
+    part = doc_tutorial.parts[4]
+    assert isinstance(part, FilePartModel)
+    destination = Path(part.destination) / "file_contents.txt"
+    assert destination.exists()
+    with open(destination) as stream:
+        assert stream.read() == "test: {{ variable }}"
+
+
+@pytest.mark.tutorial("file-contents-exists")
+def test_file_part_with_destination_exists(
+    caplog: pytest.LogCaptureFixture, tmp_path: Path, runner: LocalTutorialRunner
+) -> None:
+    """Test that file parts have a destination that already exists."""
+    runner.context["tmp_path"] = tmp_path
+    with pytest.raises(RunTutorialException):
+        runner.run()
+    assert f"{tmp_path}/destination.txt: Destination already exists" in caplog.text
+
+    # Make sure we still have the old contents
+    with open(tmp_path / "destination.txt") as stream:
+        assert stream.read() == "foo"
+
+
+@pytest.mark.tutorial("file-contents-destination-dir")
+def test_file_part_with_contents_with_destination_template(
+    caplog: pytest.LogCaptureFixture, tmp_path: Path, runner: LocalTutorialRunner
+) -> None:
+    """Test that file parts have a destination that already exists."""
+    with pytest.raises(
+        RunTutorialException,
+        match=r"^dir/: Destination is directory, but no source given to derive filename\.$",
+    ):
+        runner.run()
+    assert "dir/: Destination is directory, but no source given to derive filename." in caplog.text
diff --git a/tests/runners/local/test_local.py b/tests/runners/local/test_local.py
@@ -10,7 +10,7 @@
 from pytest_subprocess import FakeProcess
 
 from structured_tutorials.errors import RunTutorialException
-from structured_tutorials.models import FilePartModel, TutorialModel
+from structured_tutorials.models import TutorialModel
 from structured_tutorials.runners.local import LocalTutorialRunner
 from tests.conftest import DOCS_TUTORIALS_DIR, TEST_TUTORIALS_DIR
 
@@ -55,76 +55,6 @@ def test_skip_part(fp: FakeProcess) -> None:
     runner.run()
 
 
-@pytest.mark.doc_tutorial("file-copy")
-def test_file_copy(tmp_path: Path, doc_tutorial: TutorialModel) -> None:
-    """Test skipping a part when running."""
-    # Update destination to copy to tmp_path
-    for part in doc_tutorial.parts:
-        assert isinstance(part, FilePartModel)
-        part.destination = str(tmp_path) + part.destination
-    runner = LocalTutorialRunner(doc_tutorial, interactive=False)
-    runner.run()
-
-    part = doc_tutorial.parts[0]
-    assert isinstance(part, FilePartModel)
-    assert Path(part.destination).exists()
-    with open(part.destination) as stream:
-        assert stream.read() == "inline contents: at runtime"
-
-    part = doc_tutorial.parts[1]
-    assert isinstance(part, FilePartModel)
-    assert Path(part.destination).exists()
-    with open(part.destination) as stream:
-        assert stream.read() == "inline contents: {{ variable }}"
-
-    part = doc_tutorial.parts[2]
-    assert isinstance(part, FilePartModel)
-    assert Path(part.destination).exists()
-    with open(part.destination) as stream:
-        assert stream.read() == "test: at runtime"
-
-    part = doc_tutorial.parts[3]
-    assert isinstance(part, FilePartModel)
-    assert Path(part.destination).exists()
-    with open(part.destination) as stream:
-        assert stream.read() == "test: {{ variable }}"
-
-    part = doc_tutorial.parts[4]
-    assert isinstance(part, FilePartModel)
-    destination = Path(part.destination) / "file_contents.txt"
-    assert destination.exists()
-    with open(destination) as stream:
-        assert stream.read() == "test: {{ variable }}"
-
-
-@pytest.mark.tutorial("file-contents-exists")
-def test_file_part_with_destination_exists(
-    caplog: pytest.LogCaptureFixture, tmp_path: Path, runner: LocalTutorialRunner
-) -> None:
-    """Test that file parts have a destination that already exists."""
-    runner.context["tmp_path"] = tmp_path
-    with pytest.raises(RunTutorialException):
-        runner.run()
-    assert f"{tmp_path}/destination.txt: Destination already exists" in caplog.text
-
-    # Make sure we still have the old contents
-    with open(tmp_path / "destination.txt") as stream:
-        assert stream.read() == "foo"
-
-
-@pytest.mark.tutorial("file-contents-destination-dir")
-def test_file_part_with_contents_with_destination_template(
-    caplog: pytest.LogCaptureFixture, tmp_path: Path, runner: LocalTutorialRunner
-) -> None:
-    """Test that file parts have a destination that already exists."""
-    with pytest.raises(
-        RunTutorialException,
-        match=r"^dir/: Destination is directory, but no source given to derive filename\.$",
-    ):
-        runner.run()
-    assert "dir/: Destination is directory, but no source given to derive filename." in caplog.text
-
-
 def test_temporary_directory(tmp_path: Path, fp: FakeProcess) -> None:
     """Test running in temporary directory."""
     fp.register("pwd")
diff --git a/tests/sphinx/test_wrapper.py b/tests/sphinx/test_wrapper.py
