Doc: Use real-life workshop examples

docs/.custom_wordlist.txt

@@ -81,7 +81,6 @@ html
 http
 https
 IDEs
-imagenet
 init
 intraworkshop
 IoT

docs/examples/workshop-notebook.yaml

@@ -0,0 +1,29 @@
+name: notebook
+base: ubuntu@24.04
+sdks:
+  - name: ollama
+    channel: vulkan/stable
+  - name: uv
+    slots:
+      api:
+        interface: tunnel
+        endpoint: 8000
+  - name: jupyter
+  - name: system
+    plugs:
+      jupyter:
+        interface: tunnel
+        endpoint: 127.0.0.1:8989
+      app:
+        interface: tunnel
+        endpoint: 127.0.0.1:8090
+      inference:
+        interface: tunnel
+        endpoint: 127.0.0.1:11434
+connections:
+  - plug: jupyter:venv
+    slot: uv:venv
+  - plug: system:app
+    slot: uv:api
+  - plug: system:inference
+    slot: ollama:ollama-server

docs/explanation/workshops/concepts.rst

@@ -329,43 +329,54 @@ eventually, all interface connections are
 in a single task *after* all the SDK layers have been created,
 because all components must be in place before the wiring can be done.
 
-This example adds a slot, a plug, and a connection to its SDKs:
+This example adds a slot, a plug, and two connections to its SDKs:
 
 .. code-block:: yaml
    :caption: .workshop/dev.yaml
-   :emphasize-lines: 5-8, 10-13, 15-17
+   :emphasize-lines: 5-8, 11-14, 15-19
 
-   base: ubuntu@22.04
    name: dev
+   base: ubuntu@24.04
    sdks:
-     - name: tensorflow
-       plugs:
-         cuda:
-           interface: mount
-           workshop-target: /usr/local/cuda/lib64
-     - name: imagenet
+     - name: uv
        slots:
-         images:
-           interface: mount
-           workshop-source: $SDK/images
-     - name: cuda
+         api:
+           interface: tunnel
+           endpoint: 8000
+     - name: jupyter
+     - name: system
+       plugs:
+         app:
+           interface: tunnel
+           endpoint: 127.0.0.1:8090
    connections:
-     - plug: tensorflow:cuda
-       slot: cuda:libs
+     - plug: jupyter:venv
+       slot: uv:venv
+     - plug: system:app
+       slot: uv:api
+
 
+This extends the :samp:`uv` SDK
+with a tunnel slot for a service its publisher never declared,
+and the :samp:`system` SDK
+with a tunnel plug that exposes that service on the host.
 
-This extends the :samp:`tensorflow` SDK
-with a standard path for CUDA runtime libraries.
-In :samp:`connections`,
-we explicitly connect the :samp:`cuda` plug,
-newly defined under the :samp:`tensorflow` SDK,
-to the :samp:`libs` slot from the :samp:`cuda` SDK.
+The first entry in :samp:`connections`
+wires a plug and a slot that the SDKs define themselves.
 Thus, upon workshop creation,
-the plug will be connected
+the :samp:`jupyter:venv` plug will be connected
 not to a default system SDK location on the host
 (for example, :file:`.../<ID>/<WORKSHOP>/...`),
-but to a library path *inside* the workshop,
-which is set by :samp:`workshop-target`.
+but to a directory *inside* the workshop,
+which the :samp:`uv:venv` slot sets with :samp:`workshop-source`.
+
+The second entry connects the :samp:`app` plug,
+newly defined under the :samp:`system` SDK,
+to the :samp:`api` slot,
+newly defined under the :samp:`uv` SDK.
+It is needed because the two names differ:
+on its own, |ws_markup| pairs a tunnel plug under the :samp:`system` SDK
+only with a slot that carries the same name.
 
 Mind that the connection established in this way
 is no different from those created via the command line.

docs/reference/definition-files/_interfaces/mount.rst

@@ -27,6 +27,11 @@ A mount plug is described by these attributes:
      - Path inside the workshop used as the plug's target directory.
        Must be an absolute path;
        :envvar:`$SDK` expands to the SDK's installation path in the workshop.
+       |ws_markup| creates the directory if it is missing,
+       so the path must be writable.
+       An SDK's installation tree is mounted read-only,
+       so a target inside it resolves
+       only where the SDK already ships that directory.
 
    * - :samp:`mode`
      - integer
@@ -79,3 +84,5 @@ A mount slot on a regular SDK is described by this attribute:
      - Path inside the workshop used as the slot's source directory.
        Must be an absolute path;
        :envvar:`$SDK` expands to the SDK's installation path in the workshop.
+       The directory must already exist when the connection is established;
+       unlike a plug's target, |ws_markup| does not create it.

docs/reference/definition-files/workshop-definition.rst

@@ -332,23 +332,35 @@ Workshop with an in-project SDK and a plug binding between SDKs:
    :language: yaml
    :caption: .workshop/go-dev.yaml
 
-Workshop that grafts a plug and a slot onto its SDKs
+
+Workshop that grafts a slot and three plugs onto its SDKs
 and adds explicit connections;
-besides using the fictional
-:samp:`tensorflow`, :samp:`imagenet` and :samp:`cuda` SDKs,
-it defines an additional slot under the :samp:`imagenet` SDK,
-a plug under :samp:`tensorflow`,
-and two connections:
+besides using the :samp:`ollama`, :samp:`uv` and :samp:`jupyter` SDKs,
+it defines an additional tunnel slot under the :samp:`uv` SDK,
+three tunnel plugs under the :samp:`system` SDK,
+and three connections:
+
+- One that connects the :samp:`jupyter:venv` plug
+  to the :samp:`uv:venv` slot, both provided by the SDKs themselves.
+  Without it, :samp:`jupyter:venv` falls back to :samp:`system:mount`
+  and Jupyter gets a private virtual environment on the host.
+
+- One that connects the newly defined :samp:`system:app` plug
+  to the newly defined :samp:`uv:api` slot.
+
+- One that connects the newly defined :samp:`system:inference` plug
+  to the preexisting :samp:`ollama:ollama-server` slot.
 
-- One that connects the :samp:`tensorflow:images` plug
-  to the newly defined :samp:`imagenet:images` slot.
 
-- Another that connects the :samp:`tensorflow:cuda` plug
-  to the preexisting :samp:`cuda:libs`.
+The last two connections are required because the names differ:
+a tunnel plug under the :samp:`system` SDK auto-connects
+only to a slot that carries the same name.
+The :samp:`system:jupyter` plug needs no entry for that reason,
+pairing with the :samp:`jupyter:jupyter` slot on its own.
 
-.. literalinclude:: ../../examples/workshop-digits-cuda.yaml
+.. literalinclude:: ../../examples/workshop-notebook.yaml
    :language: yaml
-   :caption: .workshop/digits-cuda.yaml
+   :caption: .workshop/notebook.yaml
 
 
 Workshop that pulls an SDK from the try area: