doc: add examples section to docs (#13)

#### Relevant issue or PR
<!-- If the changes resolve an issue or follow some other PR, link to
them here. GitHub references are strongly preferred, but links to other
resources, such as Jira or Confluence, can also be used. Only link
something if it is directly relevant. -->
Cherry picked from #9.

#### Description of changes
<!-- Add a high-level description of changes, focusing on the *what* and
*why*. -->
Adds examples section to Sphinx generated ReadTheDocs. Won't work until
#12 is merged, since it relies on the new directory structure in the
`examples/` folder.

#### Testing done
<!-- Describe how the changes were tested; e.g., "CI passes", "Tested
manually in stagingrepo#123", screenshots of a terminal session that
verify the changes, or any other evidence of testing the changes. -->

Author: jacanchaplais

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/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!