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

Parameterize version numbers in docs

Author: mangelajo

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}