Merge pull request #177 from jumpstarter-dev/dynamic-version-in-doc

Parameterize version numbers in docs

docs/source/api-reference/adapters.md

@@ -0,0 +1,11 @@
+# Adapter API Reference
+
+```{warning}
+This project is still evolving, so these docs may be incomplete or out-of-date.
+```
+
+### Adapters
+```{eval-rst}
+.. automodule:: jumpstarter.client.adapters
+    :members:
+```

docs/source/api-reference/drivers.md

@@ -18,12 +18,6 @@ This project is still evolving, so these docs may be incomplete or out-of-date.
     :members:
 ```
 
-### Adapters
-```{eval-rst}
-.. automodule:: jumpstarter.client.adapters
-    :members:
-```
-
 ## Example
 ```{testsetup} *
 import jumpstarter.common.importlib

docs/source/api-reference/index.md

@@ -4,5 +4,6 @@ This section provides details on the Jumpstarter core API and contrib drivers.
 
 ```{toctree}
 drivers.md
+adapters.md
 contrib/index.md
 ```

docs/source/cli/getting-started.md

@@ -12,7 +12,11 @@ configurations, and run transient or persistent exporter instances.
 
 The `jmp` and `jmp-exporter` CLI tools are available as part of the `jumpstarter` Python package.
 You can learn how to install this package [here](../installation/python-package.md),
-but it is also available as a container image `quay.io/jumpstarter/jumpstarter:main`.
+but it is also available as a container image
+```{code-block}
+:substitutions:
+quay.io/jumpstarter/jumpstarter:{{version}}
+```
 
 To check if you have the client CLI installed, run:
 

docs/source/cli/run-tests.md

@@ -14,20 +14,12 @@ service.
 Alternatively the client can receive the endpoint and token as environment variables:
 
 ```bash
-export JUMPSTARTER_ENDPOINT=jumpstarter.my-lab.com:1443
-export JUMPSTARTER_TOKEN=dGhpc2lzYXRva2VuLTEyMzQxMjM0MTIzNEyMzQtc2Rxd3Jxd2VycXdlcnF3ZXJxd2VyLTEyMzQxMjM0MTIz
+export JMP_ENDPOINT=jumpstarter.my-lab.com:1443
+export JMP_TOKEN=dGhpc2lzYXRva2VuLTEyMzQxMjM0MTIzNEyMzQtc2Rxd3Jxd2VycXdlcnF3ZXJxd2VyLTEyMzQxMjM0MTIz
 ```
 
 This is useful for CI/CD systems that inject the environment variables into the pipeline.
 
-A custom location to the client configuration can also be passed using the following
-environment variable. This is useful in situations where there are multiple client
-configurations or in an environment when the config is mounted as a file.
-
-```bash
-export JUMPSTARTER_CONFIG=/etc/jumpstarter/my-client.yaml
-```
-
 ## Running tests locally (without a server)
 
 When no client configuration or environment variables are set, the client will

docs/source/conf.py

@@ -18,7 +18,14 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinxcontrib.mermaid", "myst_parser", "sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx_click"]
+extensions = [
+    "sphinxcontrib.mermaid",
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx_click",
+    "sphinx_substitution_extensions",
+]
 
 templates_path = ["_templates"]
 exclude_patterns = []
@@ -32,4 +39,13 @@
 # html_static_path = ["_static"]
 html_extra_path = ["extra"]
 html_title = "Jumpstarter Docs"
+
 myst_heading_anchors = 3
+myst_enable_extensions = [
+    "substitution",
+]
+myst_substitutions = {
+    "requires_python": ">=3.11",
+    "version": "0.5.0",
+    "controller_version": "0.5.0",
+}

docs/source/config.md

@@ -224,15 +224,11 @@ The exporter configuration may also be provided by environment variables which
 may be useful in CI or when writing a script that uses Jumpstarter.
 
 - `JUMPSTARTER_GRPC_INSECURE` - Set to `1` to disable TLS verification.
-- `JMP_EXPORTER_CONFIG` - A path to a exporter configuration YAML file
 to use.
-- `JMP_EXPORTER` - The name of a registered exporter config to use.
 - `JMP_ENDPOINT` - The gRPC endpoint of the Jumpstarter controller server
 (overrides the config value).
 - `JMP_TOKEN` - An exporter auth token generated by the controller
 (overrides the config value).
-- `JMP_DRIVERS` - A comma-separated list of allowed driver namespaces
-to automatically load (overrides the config value).
 
 ## Running an Exporter
 
@@ -244,11 +240,12 @@ the network.
 
 To run the exporter container on a test runner using Podman:
 
-```bash
+```{code-block} bash
+:substitutions:
 $ sudo podman run --rm -ti --name my-exporter --net=host  --privileged \
                 -e JUMPSTARTER_GRPC_INSECURE=1 \
                 -v /run/udev:/run/udev -v /dev:/dev -v /etc/jumpstarter:/etc/jumpstarter \
-                quay.io/jumpstarter-dev/jumpstarter:main \
+                quay.io/jumpstarter-dev/jumpstarter:{{version}} \
                 jmp-exporter run my-exporter
 
 INFO:jumpstarter.exporter.exporter:Registering exporter with controller
@@ -269,15 +266,16 @@ To run the exporter as a service podman-systemd is recommended, by using podman-
 you can simply create a systemd service file at `/etc/containers/systemd/my-exporter.container` with
 the following content:
 
-```ini
+```{code-block} ini
+:substitutions:
 [Unit]
 Description=My exporter
 
 [Container]
 ContainerName=my-exporter
 Environment=JUMPSTARTER_GRPC_INSECURE=1
 Exec=jmp-exporter run my-exporter
-Image=quay.io/jumpstarter-dev/jumpstarter:main
+Image=quay.io/jumpstarter-dev/jumpstarter:{{version}}
 Network=host
 PodmanArgs=--privileged
 Volume=/run/udev:/run/udev

docs/source/drivers.md

@@ -15,8 +15,8 @@ Drivers in Jumpstarter consist of three components:
 
 - `Driver` - Implements the logic to configure and use the interface(s) provided
 by the host system. e.g. a TCP port.
-- `DriverInterface` - Defines the contract between the driver client and the
-driver itself.
+- `DriverInterface` - Optionally defines the contract between the driver client and the
+driver itself, so multiple drivers can share the same client.
 - `DriverClient` - Provides a user-friendly interface that can be used byclients
 to interact with the underlying `Driver` either locally or remotely over the network.
 
@@ -25,8 +25,8 @@ The exporter instance runs the `Driver` itself to interact with the hardware.
 Clients use a `DriverClient` class to interact with the driver through the
 contract defined in the `DriverInterface`.
 
-When a client connects to the exporter and requests a lease, a session is created
-for each set of tests to execute. Within the session, the specified `Driver`
+When a client requests a lease and  connects to the exporter, a session is created
+for all the tests the client has to execute. Within the session, the specified `Driver`
 subclass is instantiated for each of the configured interfaces defined in the
 exporter configuration. These driver instances live throughout the duration of
 the session and can run setup/teardown logic and keep state internally for that

docs/source/installation/container-jmp.md

@@ -7,10 +7,11 @@ packages locally, you can create an alias to run the `jmp` client in a container
 It is recommended to add the alias to your shell profile.
 ```
 
-```bash
+```{code-block} bash
+:substitutions:
 $ alias jmp='podman run --rm -it -e JUMPSTARTER_GRPC_INSECURE=1 \
               -v "${HOME}/.config/jumpstarter/:/root/.config/jumpstarter" \
-               quay.io/jumpstarter-dev/jumpstarter:main jmp'
+               quay.io/jumpstarter-dev/jumpstarter:{{version}} jmp'
 ```
 
 Then you can try:
@@ -30,13 +31,14 @@ to mount access to devices into the container, provide host network access,
 and run the container in privileged mode, this probably needs to be run as **root**.
 
 
-```bash
+```{code-block} bash
+:substitutions:
 $ mkdir -p "${HOME}/.config/jumpstarter/" /etc/jumpstarter
 
 # you may want to add this alias to the profile
 $ alias jmp-exporter='podman run --rm -it -e JUMPSTARTER_GRPC_INSECURE=1 \
               -v "${HOME}/.config/jumpstarter/:/root/.config/jumpstarter" \
               --net=host  --privileged \
               -v /run/udev:/run/udev -v /dev:/dev -v /etc/jumpstarter:/etc/jumpstarter \
-              quay.io/jumpstarter-dev/jumpstarter:main jmp-exporter'
+              quay.io/jumpstarter-dev/jumpstarter:{{version}} jmp-exporter'
 ```

docs/source/installation/index.md

@@ -10,7 +10,7 @@ The Jumpstarter components which can be installed are:
 | ---------                 | -----------                                                   |
 | jumpstarter-controller    | The Jumpstarter Controller service, runs in k8s, manages exporters, clients, leases,  and provides routing |
 | jmpctl                    | The Jumpstarter administrator CLI tool, simplifies the administrator experience when managing clients or exporters on the controller |
-| jmp / j / python packages | The Jumpstarter Python package. This is necessary to lease ad interact with the exporters, it's also the component ran on the exporter hosts as a service. In most cases installation is not necessary and can be consumed through a container.  |
+| jmp /jmp-exporter / j / python packages | The Jumpstarter Python package. This is necessary to lease and interact with the exporters, it's also the component ran on the exporter hosts as a service. In most cases installation is not necessary and can be consumed through a container.  |
 
 
 ```{toctree}

docs/source/installation/python-package.md

@@ -9,7 +9,7 @@ This package includes:
 - The client CLI tool.
 - An exporter runtime and built-in drivers.
 
-The Python package can be installed using ``pip`` or similar, Python 3.10 or newer is required.:
+The Python package can be installed using ``pip`` or similar, Python {{requires_python}} is required.:
 
 <!-- TODO: create meta-package-to-install-all -->
 
@@ -32,4 +32,4 @@ $ source ~/.venv/jumpstarter/bin/activate
 $ pip3 install ....
 ```
 
-An alternative to installing the packages is to [use the container package](./container-jmp.md).
+An alternative to installing the packages is to [use the container package](./container-jmp.md).

docs/source/installation/service-cli.md

@@ -7,9 +7,10 @@ Please refer to https://github.com/jumpstarter-dev/jumpstarter-controller/releas
 the latest release.
 
 ## Installing the CLI
-```bash
-export VERSION=0.1.0
-export ARCH=amd64
+```{code-block} bash
+:substitutions:
+export VERSION={{controller_version}}
+export ARCH=amd64 # or arm64
 
 curl -L https://github.com/jumpstarter-dev/jumpstarter-controller/releases/download/${VERSION}/jmpctl_${VERSION}_linux_${ARCH} \
      -o /usr/local/bin/jmpctl

docs/source/installation/service/kind-helm.md

@@ -58,7 +58,8 @@ kind create cluster  --config kind_config.yaml
 
 ### Install Jumpstarter
 
-```bash
+```{code-block} bash
+:substitutions:
 export BASEDOMAIN="jumpstarter.${IP}.nip.io"
 export GRPC_ENDPOINT="grpc.${BASEDOMAIN}:8082"
 export GRPC_ROUTER_ENDPOINT="router.${BASEDOMAIN}:8083"
@@ -71,6 +72,5 @@ helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarte
             --set global.metrics.enabled=false \
             --set jumpstarter-controller.grpc.nodeport.enabled=true \
             --set jumpstarter-controller.grpc.mode=nodeport \
-            --version=0.1.0
-        {{< / highlight >}}
-```
+            --version={{controller_version}}
+```

docs/source/installation/service/kubernetes-helm.md

@@ -11,11 +11,12 @@ Please note that `global.baseDomain` is used to create the host names for the se
 with the provided example the services will be available at grpc.jumpstarter.example.com
 ```
 
-```bash
-    helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarter \
-            --create-namespace --namespace jumpstarter-lab \
-            --set global.baseDomain=jumpstarter.example.com \
-            --set global.metrics.enabled=true # disable if metrics not available \
-            --set jumpstarter-controller.grpc.mode=ingress \
-            --version=0.1.0
-```
+```{code-block} bash
+:substitutions:
+helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarter \
+        --create-namespace --namespace jumpstarter-lab \
+        --set global.baseDomain=jumpstarter.example.com \
+        --set global.metrics.enabled=true `# disable if metrics not available` \
+        --set jumpstarter-controller.grpc.mode=ingress \
+        --version={{controller_version}}
+```

docs/source/installation/service/minikube-helm.md

@@ -29,7 +29,8 @@ export IP=$(minikube ip)
 ```
 
 ### Install Jumpstarter
-```bash
+```{code-block} bash
+:substitutions:
 export BASEDOMAIN="jumpstarter.${IP}.nip.io"
 export GRPC_ENDPOINT="grpc.${BASEDOMAIN}:8082"
 export GRPC_ROUTER_ENDPOINT="router.${BASEDOMAIN}:8083"
@@ -42,5 +43,5 @@ helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarte
             --set global.metrics.enabled=false \
             --set jumpstarter-controller.grpc.nodeport.enabled=true \
             --set jumpstarter-controller.grpc.mode=nodeport \
-            --version=0.1.0
-```
+            --version={{controller_version}}
+```

docs/source/installation/service/openshift-argocd.md

@@ -63,7 +63,8 @@ auto-generate values for these, but with ArgoCD such mechanism doesn't work. You
 create these secrets in the namespace where the jumpstarter is installed.
 ```
 
-```yaml
+```{code-block} yaml
+:substitutions:
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
@@ -89,6 +90,6 @@ spec:
       - name: jumpstarter-controller.grpc.mode
         value: "route"
     repoURL: quay.io/jumpstarter-dev/helm
-    targetRevision: "0.1.0"
+    targetRevision: "{{controller_version}}"
 ```
 

docs/source/installation/service/openshift-helm.md

@@ -12,13 +12,14 @@ this is because the install process will install some CRDs and ClusterRoles.
 
 To install using helm:
 
-```bash
-  helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarter \
-              --create-namespace --namespace jumpstarter-lab \
-              --set global.baseDomain=jumpstarter.example.com \
-              --set global.metrics.enabled=true \
-              --set jumpstarter-controller.grpc.mode=route \
-              --version=0.1.0
+```{code-block} bash
+:substitutions:
+helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarter \
+          --create-namespace --namespace jumpstarter-lab \
+          --set global.baseDomain=jumpstarter.example.com \
+          --set global.metrics.enabled=true \
+          --set jumpstarter-controller.grpc.mode=route \
+          --version={{controller_version}}
 ```
 
 

docs/source/introduction/drivers.md

@@ -65,9 +65,9 @@ device-specific functionality for your use case.
 
 Here is an example of a driver tree with two custom composite drivers:
 
-```yaml
+```
 MyDevice # Custom composite driver for the entire target device
-├─ TcpNetwork # TCP Network driver to tunnel port 8000
+├─ TcpNetwork # TCP Network driver to tunnel port 8000
 ├─ MyPower # Custom power driver to control device power
 ├─ SDWire # SD Wire storage emulator to enable re-flash on demand
 ├─ DigitalOutput # GPIO pin control to send signals to the device

docs/source/introduction/exporters.md

@@ -36,7 +36,7 @@ export:
 
 ## Running an Exporter
 
-To run an Exporter on a host system, you must have Python >= 3.11 installed
+To run an Exporter on a host system, you must have Python {{requires_python}} installed
 and the required driver packages installed locally.
 
 Exporters can be run in a privileged container or as a systemd daemon. It is

docs/source/introduction/service.md

@@ -34,16 +34,6 @@ a set of requested labels, similar to [node selection](https://kubernetes.io/doc
 in Kubernetes. This enable flexible CI-driven testing even when physical resources
 are limited.
 
-### Sessions
-
-Within a lease, a Session is be created to interact with the hardware.
-The lifecycle of a session typically follows that of a test suite, with some
-setup logic, a set of tests, and teardown logic to reset the hardware to a known
-state.
-
-Multiple sessions may be created within one lease, however only one session can
-exist at one time.
-
 ## Router
 
 The Router service is used by the controller to route messages between

pyproject.toml

@@ -36,6 +36,7 @@ docs = [
     "esbonio>=0.16.4",
     "sphinx-autobuild>=2024.4.16",
     "sphinx-click>=6.0.0",
+    "sphinx-substitution-extensions>=2024.10.17",
 ]
 dev = [
     "pytest>=8.3.2",