doc: add examples section to docs

README.md

@@ -97,14 +97,14 @@ This setup gives you control over what to display and how to explain it, directl
 See the example README for a basic example walk-through, or simply run the following script to see the end result!
 
 ```bash
-bash examples/run.sh
+bash examples/vectoradd_jax/run.sh
 ```
 
 This will open a browser window with the Streamlit UI where users can input values and visualise the response.
 
-| ![](examples/screenshots/header-vec-a.png) | ![](examples/screenshots/outputs.png) |
+| ![](examples/vectoradd_jax/screenshots/header-vec-a.png) | ![](examples/vectoradd_jax/screenshots/outputs.png) |
 | --------------------------------- | ---------------------------- |
-| ![](examples/screenshots/vec-b.png)        | ![](examples/screenshots/plot.png)    |
+| ![](examples/vectoradd_jax/screenshots/vec-b.png)        | ![](examples/vectoradd_jax/screenshots/plot.png)    |
 
 ## ⚠️ Current Limitations
 

docs/conf.py

@@ -7,9 +7,13 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import re
+import shutil
+from pathlib import Path
 
 from tesseract_streamlit import __version__
 
+PARENT_DIR = Path(__file__).parent.resolve()
+
 project = "tesseract-streamlit"
 copyright = "2024, The tesseract-streamlit Team @ Pasteur Labs"
 author = "The tesseract-streamlit Team @ Pasteur Labs"
@@ -55,3 +59,10 @@
 
 html_theme = "furo"
 html_static_path = ["static"]
+
+# Copy example notebooks to docs/examples folder on every build
+for example_dir in Path("../examples").glob("*/"):
+    # Copy the example directory to the docs folder
+    shutil.copytree(
+        example_dir, PARENT_DIR / "examples" / example_dir.name, dirs_exist_ok=True
+    )

docs/examples/.gitignore

@@ -0,0 +1,2 @@
+**/*
+!.gitignore

docs/index.md

@@ -11,3 +11,11 @@
 self
 api
 ```
+
+```{toctree}
+:caption: Examples
+:maxdepth: 2
+:hidden:
+
+examples/vectoradd_jax/README.md
+```

examples/vectoradd_jax/README.md

@@ -0,0 +1,86 @@
+# Visualising `vectoradd_jax` with Streamlit
+
+This example shows how to quickly generate a Streamlit app to interact with the `vectoradd_jax` Tesseract.
+Using `tesseract-streamlit`, you'll get an app with autogenerated input controls and optional Python-defined visualisations — no UI code needed! 🚀
+
+---
+
+## 📥 Step 1: Download the Example Code
+
+We'll use the `vectoradd_jax` example from `tesseract-core` version `v0.9.0`. Clone it with:
+
+```shell
+git clone --depth 1 --branch v0.9.0 https://github.com/pasteurlabs/tesseract-core.git ~/Downloads/tesseract-core
+```
+
+---
+
+## 📦 Step 2: Install Requirements
+
+Install the required packages for this example:
+
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## 🛠️ Step 3: Build and Serve the Tesseract
+
+Use the Tesseract CLI to build and serve `vectoradd_jax`:
+
+```bash
+tesseract build ~/Downloads/tesseract-core/examples/vectoradd_jax
+tesseract serve vectoradd_jax
+```
+
+> [!NOTE]
+> Make note of the `PORT` and `PROJECT ID` printed to stdout — you'll need them shortly.
+
+---
+
+## ⚡ Step 4: Generate the Streamlit App
+
+With `tesseract-streamlit` installed, generate a ready-to-run Streamlit app:
+
+```bash
+tesseract-streamlit --user-code udf.py "http://localhost:<PORT>" app.py
+```
+
+`udf.py` can be found in under `tesseract-streamlit/examples/vectoradd_jax/`.
+It contains a custom function that takes the Tesseract's inputs and outputs and drops a Plotly-powered vector addition diagram straight into the web UI — automatically! 🎯
+[Check it out](https://github.com/pasteurlabs/tesseract-streamlit/blob/main/examples/vectoradd_jax/udf.py) to see how it works.
+
+---
+
+## ▶️ Step 5: Launch the App
+
+Run your new app with:
+
+```bash
+streamlit run app.py
+```
+
+This will launch a web interface for submitting inputs, running the Tesseract, and visualising the results.
+
+---
+
+## 🖼️ Screenshots
+
+| ![](screenshots/header-vec-a.png) | ![](screenshots/outputs.png) |
+| --------------------------------- | ---------------------------- |
+| ![](screenshots/vec-b.png)        | ![](screenshots/plot.png)    |
+
+---
+
+## 🧹 Step 6: Clean Up
+
+When you're done, you can stop the Tesseract server with:
+
+```bash
+tesseract teardown <PROJECT ID>
+```
+
+---
+
+🎉 That’s it — you've transformed a running Tesseract into a beautiful Streamlit web app with interactive plots, with minimal effort from the command line!

examples/udf.py → examples/vectoradd_jax/udf.py

@@ -2,7 +2,7 @@
 import plotly.graph_objects as go
 
 
-def plot_vector_addition(inputs, outputs) -> go.Figure:  # noqa
+def plot_vector_addition(inputs, outputs) -> go.Figure:
     """Plot vector addition using the triangle method with Plotly.
 
     Adds the input vectors A and B, scaled by their associated factors.

ruff.toml

@@ -44,6 +44,8 @@ ignore = [
 # Ignore missing docstrings and type annotations for selected directories
 # Also if module imports aren't at the top of the file
 "tests/*" = ["D101", "D102", "D103", "ANN", "E402"]
+"examples/*" = ["D101", "D102", "D103", "ANN"]
+"docs/examples/*" = ["D101", "D102", "D103", "ANN"]
 
 [lint.pydocstyle]
 convention = "google"