diff --git a/README.md b/README.md index c361ae5..b6eb59d 100644 --- a/README.md +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 6846812..e408114 100644 --- a/docs/conf.py +++ b/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 + ) diff --git a/docs/examples/.gitignore b/docs/examples/.gitignore new file mode 100644 index 0000000..654617b --- /dev/null +++ b/docs/examples/.gitignore @@ -0,0 +1,2 @@ +**/* +!.gitignore diff --git a/docs/index.md b/docs/index.md index b03a3d1..7a4acfa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,3 +11,11 @@ self api ``` + +```{toctree} +:caption: Examples +:maxdepth: 2 +:hidden: + +examples/vectoradd_jax/README.md +``` diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 7430b59..0000000 --- a/examples/README.md +++ /dev/null @@ -1,72 +0,0 @@ -# vectoradd_jax - -First, we need to download the example code. Let's clone the `tesseract-core` -repo at version `0.9.0` (which is what this example was written with). -We do this at a depth of 1 to prevent cloning the repo's whole history. - -```shell -git clone --depth 1 --branch v0.9.0 https://github.com/pasteurlabs/tesseract-core.git ~/Downloads/tesseract-core -``` - -`tesseract-streamlit` gives users the option to pass some custom code, see -the info about `udf.py` later. -You can use whatever packages you like to write this code; for this example, -we have put the required packages in `requirements.txt`. - -```shell -pip install -r requirements.txt -``` - -Next, we can build and serve `vectoradd_jax`, which is the Tesseracct we will -be creating a Streamlit app for here. - -```shell -tesseract build ~/Downloads/tesseract-core/examples/vectoradd_jax -tesseract serve vectoradd_jax -``` - -Make a note of the `port` and `project_id` randomly assigned by -`tesseract serve`, which will print to `stdout`, as it will be useful in the -next steps. - -If you haven't already followed the [installation guide](../README.md#-installation) to -install `tesseract-streamlit`, we recommend doing this now. -We will use the command of the same name that comes with the package to -automatically generate the Streamlit app! - -```shell -tesseract-streamlit --user-code udf.py "http://localhost:" app.py -``` - -Here we have passed `udf.py`, which contains a single user-defined function -(hence the name). It takes the inputs and outputs from the Tesseract, and -returns a Plotly figure. You aren't limited to using Plotly, any visualisation -library supported by Streamlit is fine. The list can be seen [here][stplots]. -Users may also write functions to plot the inputs or outputs alone. - -Functions may have any name, and the docstrings will be used as descriptions -in the web-app accompanying the plots. -Just make sure to name the parameters `input_schema` and / or `output_schema` -accordingly, and `tesseract-streamlit` will handle the rest. - -Finally, we can run our app! Since we have generated a Streamlit app to call -our Tesseract, we spin it up using `streamlit run`. - -```shell -streamlit run app.py -``` - -Hey presto! You should have a web-app with automatically generated inputs for -the `vectoradd_jax` Tesseract, with some custom visualisations! - - -| ![](screenshots/header-vec-a.png) | ![](screenshots/outputs.png) | -| --------------------------------- | ---------------------------- | -| ![](screenshots/vec-b.png) | ![](screenshots/plot.png) | - -When you finish up, you may want to stop serving the Tesseract. You can do this -with - -```shell -tesseract teardown -``` diff --git a/examples/vectoradd_jax/README.md b/examples/vectoradd_jax/README.md new file mode 100644 index 0000000..c5cf223 --- /dev/null +++ b/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:" 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 +``` + +--- + +πŸŽ‰ 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! diff --git a/examples/requirements.txt b/examples/vectoradd_jax/requirements.txt similarity index 100% rename from examples/requirements.txt rename to examples/vectoradd_jax/requirements.txt diff --git a/examples/run.sh b/examples/vectoradd_jax/run.sh similarity index 100% rename from examples/run.sh rename to examples/vectoradd_jax/run.sh diff --git a/examples/screenshots/header-vec-a.png b/examples/vectoradd_jax/screenshots/header-vec-a.png similarity index 100% rename from examples/screenshots/header-vec-a.png rename to examples/vectoradd_jax/screenshots/header-vec-a.png diff --git a/examples/screenshots/outputs.png b/examples/vectoradd_jax/screenshots/outputs.png similarity index 100% rename from examples/screenshots/outputs.png rename to examples/vectoradd_jax/screenshots/outputs.png diff --git a/examples/screenshots/plot.png b/examples/vectoradd_jax/screenshots/plot.png similarity index 100% rename from examples/screenshots/plot.png rename to examples/vectoradd_jax/screenshots/plot.png diff --git a/examples/screenshots/vec-b.png b/examples/vectoradd_jax/screenshots/vec-b.png similarity index 100% rename from examples/screenshots/vec-b.png rename to examples/vectoradd_jax/screenshots/vec-b.png diff --git a/examples/udf.py b/examples/vectoradd_jax/udf.py similarity index 96% rename from examples/udf.py rename to examples/vectoradd_jax/udf.py index 6527ade..0a1a906 100644 --- a/examples/udf.py +++ b/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. diff --git a/ruff.toml b/ruff.toml index 1c08a8d..f9fc8dd 100644 --- a/ruff.toml +++ b/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"