add option for skipping

Author: mathiasertl

docs/reference.rst

@@ -87,6 +87,32 @@ The second part will test if ``ncat`` is installed and call it after a three-sec
 
 .. structured-tutorial-part::
 
+Skip a part at runtime
+======================
+
+To skip an entire part at runtime, but still show it in documentation, you can use the ``skip`` configuration:
+
+.. literalinclude:: /tutorials/skip-part-run/tutorial.yaml
+    :language: yaml
+
+When running the tutorial, only the first part will run:
+
+.. code-block:: console
+
+    user@host:~$ structured-tutorial docs/tutorials/skip-part-run/tutorial.yam
+    + ls /etc
+    ...
+
+But when generating documentation, both parts will show, for example, this is part one:
+
+.. structured-tutorial:: skip-part-run/tutorial.yaml
+
+.. structured-tutorial-part::
+
+... and this is part two:
+
+.. structured-tutorial-part::
+
 ********************
 Documenting commands
 ********************
@@ -155,3 +181,30 @@ This will render as:
 .. structured-tutorial:: prompt/tutorial.yaml
 
 .. structured-tutorial-part::
+
+Skip a part in documentation
+============================
+
+To skip an entire part for documentation purposes, but still use it at runtime, you can use the ``skip``
+configuration:
+
+.. literalinclude:: /tutorials/skip-part-doc/tutorial.yaml
+    :language: yaml
+
+When running the tutorial, only the first part will run:
+
+.. code-block:: console
+
+    user@host:~$ structured-tutorial docs/tutorials/skip-part-run/tutorial.yaml
+    + ls /tmp
+    ...
+    + ls /etc
+    ...
+
+But when generating documentation, only the first part can be used. Calling ``structured-tutorial-part`` a
+second time will lead to an error (as there are no parts left).
+
+.. structured-tutorial:: skip-part-doc/tutorial.yaml
+
+.. structured-tutorial-part::
+

docs/tutorials/file-copy/tutorial.yaml

@@ -0,0 +1,29 @@
+cwd: ../../
+configuration:
+  doc:
+    context:
+      variable: at docs
+  run:
+    context:
+      variable: at runtime
+parts:
+  # Create a file with contents specified inline
+  - contents: "inline contents: {{ variable }}"
+    destination: build/inline_contents.txt
+  # You can also disable rendering of contents as template
+  - contents: "inline contents: {{ variable }}"
+    destination: build/inline_contents.txt.template
+    template: false
+  # Create a file based on contents from another file.
+  # NOTE: source path is relative to "this file" / "cwd from top-level configuration"
+  - source: tests/data/tutorials/file_contents.txt
+    destination: build/file_contents.txt
+  # Create a file based on contents from another file, but do not render it
+  # as a template (e.g. b/c you want to show the template, it's very large, a binary file, ...)
+  - source: tests/data/tutorials/file_contents.txt
+    destination: build/file_contents.txt.template
+    template: false
+  # You can also name a destination directory
+  - source: tests/data/tutorials/file_contents.txt
+    destination: build/subdir/
+    template: false

docs/tutorials/skip-part-doc/tutorial.yaml

@@ -0,0 +1,14 @@
+parts:
+  - commands:
+      - command: ls /tmp
+        doc:
+          output: ...
+    # We could also skip part at runtime instead:
+    #run:
+    #  skip: true
+    doc:
+      skip: true
+  - commands:
+      - command: ls /etc
+        doc:
+          output: ...

docs/tutorials/skip-part-run/tutorial.yaml

@@ -0,0 +1,20 @@
+parts:
+  - commands:
+      - command: ls /tmp
+        doc:
+          output: ...
+    run:
+      skip: true
+    # We could also skip part in documentation instead:
+    #doc:
+    #  skip: true
+  - commands:
+      - command: ls /etc
+        doc:
+          output: ...
+      # Or we could skip just a command, not the entire part, at runtime:
+      - command: ls /tmp
+        run:
+          skip: true
+        doc:
+          output: ...

docs/tutorials/test-command/tutorial.yaml

@@ -10,6 +10,8 @@ parts:
   - commands:
       # Verify that ncat is installed - apt install ncat
       - command: which ncat
+        doc:
+          output: /usr/bin/ncat
       # TODO: retrieve pid from stdout
       # Start an ncat echo server, but have a delay of three seconds
       - command: "sleep 3s && ncat -e /bin/cat -k -l 1234 &"

structured_tutorials/models.py

@@ -1,5 +1,6 @@
 """Basic tutorial structure."""
 
+import os
 from pathlib import Path
 from typing import Annotated, Any, Literal, Self
 
@@ -34,6 +35,12 @@ class TestSpecificationMixin:
     backoff_factor: PositiveFloat = 0  # {backoff factor} * (2 ** ({number of previous retries}))
 
 
+class ConfigurationMixin:
+    """Mixin for configuration models."""
+
+    skip: bool = False
+
+
 class CleanupCommandModel(CommandBaseModel):
     """Model for cleanup commands."""
 
@@ -59,7 +66,7 @@ class TestPortModel(TestSpecificationMixin, BaseModel):
     port: Annotated[int, Field(ge=0, le=65535)]
 
 
-class CommandRuntimeConfigurationModel(CommandBaseModel):
+class CommandRuntimeConfigurationModel(ConfigurationMixin, CommandBaseModel):
     """Model for runtime configuration when running a single command."""
 
     model_config = ConfigDict(extra="forbid")
@@ -69,7 +76,7 @@ class CommandRuntimeConfigurationModel(CommandBaseModel):
     test: tuple[TestCommandModel | TestPortModel, ...] = tuple()
 
 
-class CommandDocumentationConfigurationModel(BaseModel):
+class CommandDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
     """Model for documenting a single command."""
 
     model_config = ConfigDict(extra="forbid")
@@ -88,6 +95,18 @@ class CommandModel(BaseModel):
     doc: CommandDocumentationConfigurationModel = CommandDocumentationConfigurationModel()
 
 
+class CommandsRuntimeConfigurationModel(ConfigurationMixin, BaseModel):
+    """Runtime configuration for an entire commands part."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CommandsDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+    """Documentation configuration for an entire commands part."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
 class CommandsPartModel(BaseModel):
     """Model for a set of commands."""
 
@@ -96,11 +115,24 @@ class CommandsPartModel(BaseModel):
     type: Literal["commands"] = "commands"
     commands: tuple[CommandModel, ...]
 
+    run: CommandsRuntimeConfigurationModel = CommandsRuntimeConfigurationModel()
+    doc: CommandsDocumentationConfigurationModel = CommandsDocumentationConfigurationModel()
+
+
+class FileRuntimeConfigurationModel(ConfigurationMixin, BaseModel):
+    """Runtime configuration for a file part."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FileDocumentationConfigurationModel(ConfigurationMixin, BaseModel):
+    """Documentation configuration for a file part."""
+
+    model_config = ConfigDict(extra="forbid")
 
-class FileDocumentationConfigurationModel(BaseModel):
     # sphinx options:
     language: str = ""
-    caption: str | Literal[False] = ""
+    caption: str | Literal[False] = ""  # template
     linenos: bool = False
     lineno_start: PositiveInt | Literal[False] = False
     emphasize_lines: str = ""
@@ -113,12 +145,13 @@ class FilePartModel(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     type: Literal["file"] = "file"
-    contents: str | None = None
-    source: Path | None = None
-    destination: Path
+    contents: str | None = None  # template if property is set
+    source: Path | None = None  # template if property is set
+    destination: str  # template
     template: bool = True
 
     doc: FileDocumentationConfigurationModel = FileDocumentationConfigurationModel()
+    run: FileRuntimeConfigurationModel = FileRuntimeConfigurationModel()
 
     @field_validator("source", mode="after")
     @classmethod
@@ -135,6 +168,12 @@ def validate_contents_or_source(self) -> Self:
             raise ValueError("Only one of contents or source is allowed.")
         return self
 
+    @model_validator(mode="after")
+    def validate_destination(self) -> Self:
+        if not self.source and self.destination.endswith(os.sep):
+            raise ValueError(f"{self.destination}: Destination must not be a directory if contents is given.")
+        return self
+
 
 class RuntimeConfigurationModel(BaseModel):
     """Model for configuration at runtime."""

structured_tutorials/runners/local.py

@@ -1,10 +1,12 @@
 """Runner that runs a tutorial on the local machine."""
 
+import os
 import shutil
 import socket
 import subprocess
 import time
 from copy import deepcopy
+from pathlib import Path
 
 from jinja2 import Environment
 
@@ -62,6 +64,9 @@ def run_test(self, test: TestCommandModel | TestPortModel) -> None:
 
     def run_commands(self, part: CommandsPartModel) -> None:
         for command_config in part.commands:
+            if command_config.run.skip:
+                continue
+
             # Render the command
             command = self.render(command_config.command)
 
@@ -87,18 +92,20 @@ def run_commands(self, part: CommandsPartModel) -> None:
 
     def write_file(self, part: FilePartModel) -> None:
         """Write a file."""
-        if part.destination.is_dir() and not part.source:
-            raise RuntimeError("Destination is directory, but no source given to derive filename.")
+        destination = Path(part.destination)
 
-        if part.destination.is_dir():
-            destination = part.destination / part.source.name
-        else:
-            part.destination.parent.mkdir(parents=True, exist_ok=True)
-            destination = part.destination
+        if part.destination.endswith(os.path.sep):
+            # TODO: could happen if destination is a template
+            # if not part.source:
+            #     raise RuntimeError("Destination is directory, but no source given to derive filename.")
 
-        destination = part.destination
-        if destination.is_dir():
+            destination.mkdir(parents=True, exist_ok=True)
             destination = destination / part.source.name
+        elif destination.exists():
+            raise RuntimeError(f"{destination}: Destination already exists.")
+
+        # Create any parent directories
+        destination.parent.mkdir(parents=True, exist_ok=True)
 
         # If template=False and source is set, we just copy the file as is, without ever reading it
         if not part.template and part.source:
@@ -121,9 +128,12 @@ def write_file(self, part: FilePartModel) -> None:
 
     def run_parts(self) -> None:
         for part in self.tutorial.parts:
+            if part.run.skip:
+                continue
+
             if isinstance(part, CommandsPartModel):
                 self.run_commands(part)
-            elif isinstance(part, FilePartModel):  # pragma: no cover
+            elif isinstance(part, FilePartModel):
                 self.write_file(part)
             else:  # pragma: no cover
                 raise RuntimeError(f"{part} is not a tutorial part")