### How-to Guide Title Example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Illustrates the expected format for how-to guide titles, starting with 'How to' followed by an action and object.

```default
How to [action] [object]
```

--------------------------------

### Install and start LXD

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/fix-workshops/fix-installation.md

Install and start the LXD snap, a prerequisite for Workshop. Add yourself to the lxd group for access.

```console
$ sudo snap install --channel=6/stable lxd
$ sudo snap start --enable lxd.daemon
$ sudo snap services lxd
```

```console
$ sudo usermod -a -G lxd $USER
```

--------------------------------

### System-wide Configuration with setup-base

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.md

Example of using `setup-base` for system-wide configuration, including PATH updates, shell completion, and alternative command setup for the `uv` SDK.

```shell
sudo -u workshop mkdir -p /home/workshop/uv-venv

cat <<EOF >> /etc/profile.d/uv.sh
PATH="$SDK/bin:\$PATH"
EOF

"$SDK"/bin/uv generate-shell-completion bash > /etc/bash_completion.d/uv.sh
"$SDK"/bin/uvx --generate-shell-completion bash > /etc/bash_completion.d/uvx.sh

mkdir -p /usr/local/libexec/alternatives

cat << 'EOF' > /usr/local/libexec/alternatives/uv-pip
#!/bin/bash
exec uv pip "$@"
EOF

chmod +x /usr/local/libexec/alternatives/uv-pip
update-alternatives --install /usr/bin/pip pip /usr/local/libexec/alternatives/uv-pip 50
```

--------------------------------

### Start Sketching an SDK

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.md

Run this command to open an SDK definition in an editor. It initializes a minimal setup for hooks, plugs, and slots.

```console
$ workshop sketch-sdk
```

--------------------------------

### Project-specific Initialization with setup-project (PyTorch Installation)

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.md

Example of using `setup-project` to conditionally install PyTorch variants based on detected GPU type.

```shell
case "$GPU_TYPE" in
    nvidia)
        pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu129
        ;;
    amd)
        pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.4
        ;;
    *)
        pip install torch torchvision torchaudio
        ;;
esac
```

--------------------------------

### Docker System Setup and User-Level Project Setup

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/sdk-vs-dockerfile.md

This Dockerfile snippet demonstrates setting up system packages as root and then switching to a non-root user to install project-specific dependencies. It maps to the setup-base and setup-project hooks in Workshop.

```docker
# System setup as root (≈ setup-base)
RUN apt-get update && apt-get install -y ...

# Switch to non-root user and set up the project (≈ setup-project)
USER appuser
WORKDIR /home/appuser
RUN pip install --user ...
```

--------------------------------

### Install LXD

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.md

Install LXD using snap. This is a prerequisite for Workshop.

```console
$ sudo snap install --channel=6/stable lxd
```

--------------------------------

### Install Workshop CLI

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.md

Install the Workshop CLI using snap with the --classic option.

```console
$ sudo snap install --classic workshop
```

--------------------------------

### General Description Example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

This example shows a general description of the Workshop tool and its core concepts, focusing on dependencies and components.

```text
Workshop is a tool for defining and handling ephemeral development environments.

List your dependencies and components in YAML to define an environment. The key pieces of a definition are SDKs, independent but connectable units of functionality created by software publishers and available on the SDK Store. Workshop simplifies experiments with your environment layout.
```

--------------------------------

### Workshop Start Command Usage

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-start.rst

Displays the general usage syntax for the 'workshop start' command. Use this to understand the expected arguments and flags.

```console
$ workshop start <WORKSHOP>... [flags]
```

--------------------------------

### Bash Shell Completion Help

Source: https://github.com/canonical/workshop/blob/main/cmd/internal/doctemplates/sdk.rst

To get help on configuring Bash shell completion for persistent installation, use the '--help' flag with the 'sdk completion bash' command.

```console
$ sdk completion bash --help
```

--------------------------------

### Define SDK Platforms with Architectures

Source: https://github.com/canonical/workshop/blob/main/docs/reference/sdks.md

Specify the base image and supported CPU architectures for building and installing an SDK. This example shows a basic platform definition using architecture names.

```yaml
# ...
base: ubuntu@24.04
platforms:
  amd64:
  arm64:
```

--------------------------------

### Install Snapcraft and LXD

Source: https://github.com/canonical/workshop/blob/main/docs/contributing.md

Install Snapcraft and LXD using snap. These tools are required for building and packaging snaps locally.

```console
sudo snap install --classic snapcraft
sudo snap install --channel=6/stable lxd
```

--------------------------------

### Launch Workshop Environment

Source: https://github.com/canonical/workshop/blob/main/docs/readme.rst

Launch the configured Workshop environment. Workshop will download and install the necessary SDKs.

```console
workshop launch
```

--------------------------------

### Remount Example: Go SDK Mod-Cache

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-remount.rst

Example of remounting the 'mod-cache' plug for the 'go' SDK in the 'nimble' workshop to a new host path.

```console
$ workshop remount nimble/go:mod-cache ~/new-cache-mount
```

--------------------------------

### Start Multiple Workshops

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-start.rst

Starts the 'nimble' and 'jazzy' workshops within the current project directory. Ensure these workshops are launched before attempting to start them.

```console
$ workshop start nimble jazzy
```

--------------------------------

### Create Workshop with Go and UV SDKs

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-init.rst

Example of creating a new workshop named 'dev' and including the Go and UV SDKs.

```console
$ workshop init dev --sdks go,uv
```

--------------------------------

### Install LXD

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.md

Install a recent version of LXD using snap, ensuring it is on the 6/stable channel. This is a prerequisite for SDKcraft.

```console
sudo snap install --channel=6/stable lxd
```

--------------------------------

### Connect Plug to Slot with Target SDK Example

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-connect.rst

Connects the 'mod-cache' plug from the 'nimble/go' SDK to the 'mount' slot within the 'nimble/system' SDK. This example explicitly specifies both the source plug and the target SDK/slot.

```console
$ workshop connect nimble/go:mod-cache nimble/system:mount
```

--------------------------------

### Install SDKcraft CLI

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.md

Install the SDKcraft snap package using the --classic option. This command requires sudo privileges.

```console
sudo snap install --classic sdkcraft
```

--------------------------------

### Install LXD

Source: https://github.com/canonical/workshop/blob/main/docs/readme.rst

Install or update LXD, a prerequisite for Workshop, using snap. Ensure LXD is at version 6.8 or higher.

```console
sudo snap install --channel=6/stable lxd  # to install
```

```console
sudo snap refresh --channel=6/stable lxd  # to update
```

--------------------------------

### Install Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/readme.rst

Install the Workshop snap package using the --classic option. This method requires manual updates.

```console
sudo snap install --classic workshop
```

--------------------------------

### Starter Test Configuration

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/publish-an-sdk.md

Example of a starter test configuration for SDK testing. Defines the test summary and execution steps.

```yaml
summary: SDK installs and reports healthy
execute: |
  workshop launch --verbose --wait-on-error
  workshop info | grep -E 'status:\s+okay'
```

--------------------------------

### Launch a Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.md

Use this command to prepare a workshop for use. It starts the workshop and makes it ready for building and debugging code.

```console
$ workshop launch

  "dev" launched
```

--------------------------------

### Install Spread Testing Tool

Source: https://github.com/canonical/workshop/blob/main/docs/contributing.md

Clones the Spread repository, installs it, and ensures the bin directory is in the PATH. Download the SDKcraft release for the test suite.

```bash
git clone https://github.com/canonical/spread
cd spread
go install ./...
```

```bash
spread -h
```

--------------------------------

### Generate HTML coverage report (example)

Source: https://github.com/canonical/workshop/blob/main/docs/contributing.md

Example of generating an HTML coverage report, saving it to 'cover.html'.

```console
go tool cover -html=cover.out -o cover.html
```

--------------------------------

### Install and Enable User Systemd Service

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/build-an-sdk.md

Installs a service unit file and enables/starts the service for the current user. Use this in `setup-project` for SDKs that ship with a service.

```shell
install -D --mode=644 --target-directory ~/.config/systemd/user \
    "$SDK/<NAME>.service"

systemctl --user daemon-reload
systemctl --user enable --now <NAME>
```

--------------------------------

### Basic Console Command Example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Demonstrates a simple console command with its expected output. Use the nonselectable '$' prompt for commands.

```console
$ workshop launch dev

  Launching dev...
  Launched dev
```

--------------------------------

### Install system packages in setup-base hook

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/build-an-sdk.md

Install system-wide packages using apt-get within the setup-base hook. The apt-get command is configured to skip recommended/suggested packages and automatically confirm prompts.

```shell
apt-get update
apt-get install build-essential cmake ninja-build
```

--------------------------------

### List Revisions for a Specific SDK (Console)

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-revisions.rst

This example demonstrates how to list the available revisions for a particular SDK, such as 'my-sdk', from the store.

```console
$ sdkcraft revisions my-sdk
```

--------------------------------

### Install and Enable Ollama Service

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.md

Installs the Ollama service file and enables/starts the systemd user service.

```shell
install -D --mode=644 --target-directory ~/.config/systemd/user "$SDK/ollama.service"

systemctl --user daemon-reload
systemctl --user enable --now ollama
```

--------------------------------

### Workshop Refresh Output Example

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.md

This output indicates that the 'setup-project' hook for the 'sketch' SDK has been executed during the workshop refresh.

```console
... 
Run hook "setup-project" for "sketch" SDK
...
"dev" sketch refreshed

```

--------------------------------

### Command Usage Example

Source: https://github.com/canonical/workshop/blob/main/cmd/internal/doctemplates/command.rst

This snippet shows the basic usage syntax for a command.

```console
$ {{ .Synopsis }}
```

--------------------------------

### Create Workshop with Specific SDK Channel

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-init.rst

Example of creating a workshop with a specific channel for the Go SDK (1.26/stable).

```console
$ workshop init dev --sdks go/1.26/stable
```

--------------------------------

### Example Interaction with Synthesis Agent

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/use-workshops-with-ai-agents.md

An example of the interactive dialogue with the synthesis agent, where it asks for user preferences on implementation layout.

```text
Q: Implementation A keeps everything in :file:`app.py`,
   while Implementation B splits out helpers.
   Which layout do you prefer?

A: option B
```

--------------------------------

### Tutorial Example with Semantic Line Breaks

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

An example from a tutorial demonstrating the use of semantic line breaks in reStructuredText for improved readability and version control diffs.

```restructuredtext
Install Workshop,
upgrading the prerequisites if needed,
then ensure it runs.

Authenticate to the Snap Store and install the snap
using the `--classic <...>`_ option:
```

--------------------------------

### Multi-line Shell Command Example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Shows how to format multi-line shell commands using a backslash for continuation.

```console
$ workshop connect dev/ollama:host 127.0.0.1:11434 \
    --host-port 11434
```

--------------------------------

### Directory Structure Example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

The documentation follows the Diátaxis framework with four main sections: tutorial, how-to, explanation, and reference.

```default
docs/
├── tutorial/          # Step-by-step learning paths
├── how-to/            # Task-oriented guides
├── explanation/       # Conceptual information
└── reference/         # Technical specifications
```

--------------------------------

### External Link Examples

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Demonstrates inline and anonymous external linking conventions.

```default
`LXD documentation <https://documentation.ubuntu.com/lxd/latest/>`_
```

```default
See the `Snapcraft guide <https://snapcraft.io/docs/>`__ for details.
```

--------------------------------

### Launch Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/use-git.md

Launch the workshop to start working on your code within the defined environment. This command prepares the development workspace.

```console
$ workshop launch
```

--------------------------------

### reStructuredText Link Example for How-to Guides

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Shows how 'How to' prefixes are typically dropped in navigation links for how-to guides, using the infinitive form.

```restructuredtext
How-to guides:

* Debug issues in workshops
* Connect VS Code to a workshop
```

--------------------------------

### Project-specific Initialization with setup-project (GPU Detection)

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.md

Example of using `setup-project` to detect the available GPU type for configuring the appropriate PyTorch variant.

```shell
GPU_TYPE="none"

if command -v lspci >/dev/null 2>&1; then
    if lspci | grep -i 'NVIDIA' >/dev/null 2>&1;
 then
        GPU_TYPE="nvidia"
    elif lspci | grep -i 'AMD/ATI' >/dev/null 2>&1;
 then
        GPU_TYPE="amd"
    elif lspci | grep -i 'Intel.*Graphics' >/dev/null 2>&1;
 then
        GPU_TYPE="intel"
    fi
fi

echo "Detected GPU: $GPU_TYPE"
```

--------------------------------

### Example Go Program

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/use-git.md

A simple Go program that prints a message. This can be compiled and run within the workshop environment.

```go
package main

import "fmt"

func main() {
    fmt.Println("hello, Workshop")
}
```

--------------------------------

### Launch and Run Documentation Server

Source: https://github.com/canonical/workshop/blob/main/docs/contributing.md

Use these commands to build and run the documentation locally. Ensure you have the necessary Python environment set up.

```console
workshop launch
workshop run docs-run
```

--------------------------------

### Get Workshop Information

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.md

Check the runtime information of your launched workshop to see details about its base image, project, status, and installed SDKs.

```console
$ workshop info

  name:     dev
  base:     ubuntu@22.04
  project:  /home/user/ollama-python-project
  status:   ready
  notes:    -
  sdks:
    system:
      installed:  (1)
    ollama:
      tracking:   cpu/stable
      installed:  0.20.2  2026-04-15  (5)
      mounts:
        models:
          host-source:      .../6b79e889/dev/mount/ollama/models
          workshop-target:  /home/workshop/.ollama/models
```

--------------------------------

### Direct Instruction Example (Avoid)

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Illustrates the less preferred phrasing for instructions, using 'You can' which is discouraged.

```default
You can install Workshop with:
```

--------------------------------

### Environment Setup Hook

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.md

Sets up the PATH environment variable to include the SDK's bin directory for the Ollama service.

```shell
cat <<EOF >/etc/profile.d/ollama.sh
export PATH="$SDK/bin:\$PATH"
EOF
```

--------------------------------

### Workshop Definition Example

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/move-projects.md

A sample YAML definition for a workshop named 'golang' based on Ubuntu 22.04 with Go 1.26 SDK.

```yaml
name: golang
base: ubuntu@22.04
sdks:
  - name: go
    channel: 1.26
```

--------------------------------

### Install pre-commit hook

Source: https://github.com/canonical/workshop/blob/main/docs/contributing.md

Install the pre-commit Git hook to automatically run linters and formatters on every commit. Ensure pre-commit is installed on your system.

```console
pre-commit install
```

--------------------------------

### Initialize a New SDKcraft Project

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-init.rst

Demonstrates the basic command to initialize a new SDKcraft project in the current directory.

```console
$ sdkcraft init
```

--------------------------------

### Start Workshops

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop.md

Activates one or more specified workshops, ensuring they are launched and set to a 'Ready' state. The operation aborts if any error occurs during the process.

```console
$ workshop start nimble jazzy
```

```console
$ workshop start
```

--------------------------------

### Refresh LXD Installation

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.md

Refresh an existing LXD snap installation to the latest version.

```console
$ sudo snap refresh --channel=6/stable lxd
```

--------------------------------

### Numbered List Example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of a numbered list using pound signs for auto-numbering.

```restructuredtext
#. First step
#. Second step
#. Third step
```

--------------------------------

### Launch Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/fix-workshops/resolve-plug-conflicts.md

Launch your workshop after defining the SDKs and resolving plug conflicts with bindings.

```console
$ workshop launch digits
```

--------------------------------

### reStructuredText Example Headings

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Examples of reStructuredText headings, including a main title and a section title.

```restructuredtext
Get started with workshops
==========================

Install |ws_markup|
-------------------

Prerequisites
~~~~~~~~~~~~~
```

--------------------------------

### Metadata Block Example 2

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of a metadata block explaining the Workshop interface system.

```restructuredtext
.. meta::
   :description: A comprehensive explanation of the Workshop interface system,
                 detailing how SDKs connect to host system resources through
                 interfaces, and the mechanism of plugs and slots for resource
                 sharing between containers.
```

--------------------------------

### Metadata Block Example 1

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of a metadata block describing a practical introduction to workshops.

```restructuredtext
.. meta::
   :description: Practical introduction to workshops, guiding users through
                 defining, launching, and refreshing workshops, and executing commands in workshops.
```

--------------------------------

### Try the SDK Locally

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/publish-an-sdk.md

Packs the SDK and copies it into the try area for local testing in a workshop. This is the final pre-publish check.

```console
$ sdkcraft try
```

--------------------------------

### reStructuredText Example with Proper Nouns

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

An example of a reStructuredText heading that includes a proper noun, maintaining its capitalization.

```restructuredtext
How to use JetBrains Gateway with Workshop
==========================================
```

--------------------------------

### Stop and start workshops independently

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/use-multiple-workshops.md

Allows for stopping and starting individual workshops without affecting others in the project.

```console
$ workshop stop frontend
```

```console
$ workshop start frontend
```

--------------------------------

### Create Workshop with Specific Base Image

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-init.rst

Example of creating a workshop using a specific base image (ubuntu@22.04) for the Go SDK.

```console
$ workshop init dev --sdks go --base ubuntu@22.04
```

--------------------------------

### Refresh LXD Installation

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.md

Refresh an existing LXD installation to ensure it is on the 6/stable channel. This command requires sudo privileges.

```console
sudo snap refresh --channel=6/stable lxd
```

--------------------------------

### Run Go Build with Environment and Working Directory

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-exec.rst

Executes 'go build -x' in the 'nimble' workshop, setting the 'GO111MODULE' environment variable to 'off' and specifying '/project' as the working directory.

```console
$ workshop exec --env GO111MODULE=off -w /project nimble -- go build -x
```

--------------------------------

### sdkcraft init Command Usage

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-init.rst

Displays the general usage syntax for the 'sdkcraft init' command, including optional flags and the project directory argument.

```console
$ sdkcraft init [--name NAME] [--profile {simple}] [project_dir]
```

--------------------------------

### CLI Help String Formatting

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Demonstrates good practices for formatting short and long help strings in CLI commands, emphasizing conciseness and clarity.

```go
// Good: Single spaces, concise
Short: "Launch a new workshop",
Long: `Launch creates and starts a workshop. The workshop will be based on the configuration in workshop.yaml.`,

// Avoid: Multiple spaces or verbose explanations
Short: "Launch  a  new  workshop",
Long: `This command will launch a new workshop. It will create the workshop based on the configuration...`
```

--------------------------------

### Release Notes Metadata Example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

An example of a metadata block for release notes, specifying the description and the release notes title.

```markdown
```{eval-rst}
.. meta::
   :description: Release notes for Workshop v0.1.28, highlighting key changes,
                 new features, and bug fixes in this version.
```

# Workshop v0.1.28 release notes

```

--------------------------------

### Create Multiple Tracks for an SDK

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-create-track.rst

This example demonstrates how to create multiple tracks for a specific SDK. It shows the command with the SDK name followed by repeated --track flags for each desired track.

```console
$ sdkcraft create-track go --track 1.26 --track 1.25
```

--------------------------------

### Launch Workshop for Testing

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/publish-an-sdk.md

Launches a workshop with the SDK added to its configuration for final testing. Use --verbose for detailed output.

```console
$ workshop launch --verbose --wait-on-error
```

--------------------------------

### Initialize Python Project and Git Repository

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.md

Create a new directory for your project, navigate into it, and initialize a Git repository. This sets up the basic structure for your workshop project.

```console
$ mkdir ollama-python-project
$ cd ollama-python-project
$ git init
```

--------------------------------

### Generate Secure Setup Script with Input Validation and Escaping

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Use this pattern to generate scripts from user input. It includes input validation via whitelisting and proper escaping for sensitive parts like mount paths.

```Go
import "github.com/canonical/workshop/internal/osutil"
import "regexp"
import "fmt"

func generateSetupScript(userInput string) (string, error) {
    // Validate input first using whitelist approach
    if err := validateScriptInput(userInput); err != nil {
        return "", err
    }
    
    // Use proper escaping for mount paths
    escaped := osutil.Escape(userInput)
    script := fmt.Sprintf("#!/bin/bash\nmount %s\n", escaped)
    return script, nil
}

func validateScriptInput(input string) error {
    // Whitelist approach for allowed characters
    if !regexp.MustCompile(`^[a-zA-Z0-9_/-]+$`).MatchString(input) {
        return fmt.Errorf("invalid characters in input")
    }
    return nil
}
```

--------------------------------

### Start Interactive Shell Session

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop.md

Starts an interactive terminal session for the specified workshop. The workshop must be 'Ready' or 'Waiting'. This is a shorthand for 'workshop exec'.

```console
$ workshop shell nimble
```

```console
$ workshop shell
```

--------------------------------

### Install Python Dependencies in Jupyter

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.md

Use the `%pip` magic command within the Jupyter console to install necessary Python packages like 'requests'.

```python
In [1]: %pip install requests

```

--------------------------------

### Basic workshop launch command

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-launch.rst

Use this command to construct one or more workshops by listing their names as arguments. The command checks definitions, retrieves components, runs SDK hooks, and ties the workshop to the project.

```console
$ workshop launch <WORKSHOP>... [flags]
```

--------------------------------

### Start Single Workshop (Implicit Name)

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-start.rst

Starts the only workshop available in the current project directory when the workshop name is omitted. This is a shortcut for projects with a single workshop.

```console
$ workshop start
```

--------------------------------

### Start Jupyter Console in Workshop Shell

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.md

Activate the Jupyter virtual environment and start the Jupyter console within the workshop shell. This allows interactive work with Ollama models.

```console
$ workshop shell
workshop@dev-6b79e889:/project$ source /var/lib/workshop/sdk/jupyter/venv/bin/activate
(jupyter-venv) workshop@dev-6b79e889:/project$ jupyter console

  Jupyter console 6.6.3
  ...

```

--------------------------------

### Install github-runner SDK in Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/run-github-actions-locally.md

Add the github-runner SDK to your workshop definition to enable local GitHub Actions execution. This installs the official Runner client and a helper script.

```yaml
name: ci
base: ubuntu@24.04
sdks:
  - name: github-runner
```

--------------------------------

### Install Debian Packages in Hooks

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.md

Install Debian packages using 'apt-get' within SDK hooks, such as 'setup-base'. This leverages the system's package manager for updates and caching.

```shell
apt-get update
apt-get install ros-dev-tools
apt-get install python3-colcon-argcomplete python3-colcon-alias python3-colcon-clean python3-colcon-mixin
# ...
```

--------------------------------

### Minimize Duplication in Test Setup

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Extract common test setup into helper functions or shared constants, but allow some duplication for clarity when needed. Balance DRY principles with test self-containment.

```Go
const readyWorkshopJSON = `{
    "name": "dev",
    "status": "Ready"
}`

func (s *testSuite) setupReadyWorkshop(c *check.C) Workshop {
    return Workshop{Name: "dev", Status: "Ready"}
}
```

--------------------------------

### Basic Workflow to Launch Default Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/run-workshops-in-github-actions.md

This snippet shows the minimal configuration to check out a repository, launch the default workshop, and execute a command within it.

```yaml
on:
  pull_request:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: canonical/launch-workshop@v0
        with:
          token: ${{ secrets.WORKSHOP_TOKEN }}

      - run: workshop exec -- pytest
```

--------------------------------

### Workshop Init Command Usage

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-init.rst

Basic syntax for the 'workshop init' command, specifying the workshop name and SDKs.

```console
$ workshop init <NAME> --sdks <SDKs> [--base <BASE>] [flags]
```

--------------------------------

### Show OpenVINO SDK for All Architectures

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk-info.rst

Displays the available SDK Store channels for every supported architecture. Use the '--arch all' flag to see compatibility across different system architectures.

```console
$ sdk info openvino --arch all
```

--------------------------------

### Try SDK Locally with sdkcraft

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.md

Builds and packs the SDK for local testing. This command iterates through supported platforms, creating .sdk files containing build artifacts and metadata. Use this to verify your SDK before uploading.

```console
$ sdkcraft try

  Packed ollama_amd64_ubuntu@22.04.sdk
  Packed ollama_amd64_ubuntu@24.04.sdk
  ...

```

--------------------------------

### Add Jupyter Console Installation Hook

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.md

Add this hook to `sdk.yaml` to install Jupyter Console using the existing Jupyter SDK's virtual environment. The `setup-project` hook runs as the `workshop` user after the project is mounted.

```yaml
name: sketch

hooks:
  setup-project: |
    source /var/lib/workshop/sdk/jupyter/venv/bin/activate
    pip install jupyter-console

```

--------------------------------

### Bulleted List Example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Standard format for a bulleted list.

```restructuredtext
- Camera interface (manually connected)
- Desktop interface (manually connected)
- GPU interface (auto-connected)
```

--------------------------------

### Workshop Directory Structure Example

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/workshops/multi-workshop-patterns.md

Illustrates the directory layout for the 'One project, multiple workshops' pattern, showing how workshop definitions reside within a .workshop/ subdirectory.

```none
my-project/
├── .workshop/
│   ├── frontend.yaml
│   ├── backend.yaml
│   └── common-tools/
│       └── sdk.yaml
├── web/
└── api/
```

--------------------------------

### Launching a Workshop with Automatically Mounted Plugs

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/sdk-vs-dockerfile.md

This command launches a ROS 2 Jazzy workshop, automatically mounting any defined plugs. This simplifies setup by ensuring necessary volumes or mounts are available.

```console
$ workshop launch ros2jazzy  # the plugs are mounted automatically

```

--------------------------------

### Substitution Definitions

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of defining substitutions for reusable text replacements.

```restructuredtext
|ws_markup|    # Renders as :program:`Workshop`
|sdk_markup|   # Renders as :program:`SDKcraft`
```

--------------------------------

### YAML Endpoint Configuration

Source: https://github.com/canonical/workshop/blob/main/docs/reference/definition-files/workshop-definition.md

Use quotes for endpoints starting with '[' or '@' in YAML configuration.

```yaml
endpoint: '[::1]:8080/tcp'
endpoint: '@abstract.sock'
```

--------------------------------

### Filter First, Then Transform (Good)

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Demonstrates structuring code to filter connected plugs first, then transform them into suggestions, making the logical flow explicit.

```go
// Filter connected plugs
var connectedPlugs []Plug
for _, plug := range allPlugs {
    if len(plug.Connections) > 0 {
        connectedPlugs = append(connectedPlugs, plug)
    }
}

// Transform to suggestions
for _, plug := range connectedPlugs {
    suggestions = append(suggestions, plug.ToCompletion())
}
```

--------------------------------

### Note Admonition

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of a standard note admonition used for supplementary information.

```restructuredtext
.. note::

   For other ways to install LXD,
   see the available installation options in
   `LXD documentation <...>`_.
```

--------------------------------

### Show SDK Info Usage

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk-info.rst

Displays the general usage pattern for the 'sdk info' command. This command requires the SDK name as an argument and supports optional flags for filtering.

```console
$ sdk info <SDK> [flags]
```

--------------------------------

### Initialize Workshop Environment

Source: https://github.com/canonical/workshop/blob/main/docs/readme.rst

Initialize a Workshop environment by specifying SDKs and pinning them to specific channels. This command creates a configuration file for the environment.

```console
workshop init dev --sdks opencode,go/1.26/stable
```

--------------------------------

### Good Integration Test Example

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Demonstrates a good integration test that focuses on behavior and observable outcomes. Uses c.Mkdir for automatic cleanup of temporary directories.

```go
func (s *IntegrationSuite) TestLaunchWorkshop(c *check.C) {
    // Use c.Mkdir for automatic cleanup
    tmpDir := c.Mkdir()
    
    // Test the behavior
    err := s.cli.Launch("dev")
    c.Assert(err, check.IsNil)
    
    // Verify observable outcome
    workshops, err := s.cli.List()
    c.Assert(err, check.IsNil)
    c.Assert(workshops, check.HasLen, 1)
    c.Assert(workshops[0].Name, check.Equals, "dev")
}
```

--------------------------------

### Warning Admonition

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of a warning admonition to highlight critical information or potential risks.

```restructuredtext
.. warning::

   This will permanently delete all workshop data.
```

--------------------------------

### Refresh Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/forward-ports.md

Run this command after modifying workshop configurations to apply the changes and start the service.

```console
$ workshop refresh
```

--------------------------------

### Launching a Workshop with an Auto-Mounted Project Directory

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/sdk-vs-dockerfile.md

This command launches a ROS 2 Jazzy workshop. The project directory is automatically mounted as /project/ without explicit configuration, simplifying the setup process.

```console
$ workshop launch ros2jazzy  # must be run in the project directory

```