Merge pull request #44 from axelwalter/docs

Add documentation as pages in app

app.py

@@ -33,10 +33,12 @@ def main():
     """
     Display main page content.
     """
-    st.title("Template App")
-    st.markdown("## A template for an OpenMS streamlit app.")
+    st.title("OpenMS Streamlit Template App")
+    st.subheader("Quick Start")
     if Path("OpenMS-App.zip").exists():
-        st.markdown("## Installation")
+        st.markdow("""
+Download the latest version for Windows here by clicking the button below.
+""")
         with open("OpenMS-App.zip", "rb") as file:
             st.download_button(
                 label="Download for Windows",
@@ -45,6 +47,10 @@ def main():
                 mime="archive/zip",
                 type="primary",
             )
+        st.markdown("""
+Extract the zip file and run the executable (.exe) file to launch the app. Since every dependency is compressed and packacked the app will take a while to launch (up to one minute).
+""")
+
     save_params(params)
 
 

pages/0_📖_Installation.py

@@ -0,0 +1,61 @@
+import streamlit as st 
+from pathlib import Path
+from src.common import page_setup
+
+page_setup()
+
+if Path("OpenMS-App.zip").exists():
+    st.markdown("""
+Download the latest version for **Windows** here clicking the button below.
+""")
+    with open("OpenMS-App.zip", "rb") as file:
+        st.download_button(
+            label="Download for Windows",
+            data=file,
+            file_name="OpenMS-App.zip",
+            mime="archive/zip",
+            type="primary",
+        )
+
+st.markdown("""
+# Installation
+
+## Windows
+
+The app is available as pre-packaged Windows executable, including all dependencies.
+
+The windows executable is built by a GitHub action and can be downloaded [here](https://github.com/OpenMS/streamlit-template/actions/workflows/build-windows-executable-app.yaml).
+Select the latest successfull run and download the zip file from the artifacts section, while signed in to GitHub.
+
+## Python
+
+Clone the [streamlit-template repository](https://github.com/OpenMS/streamlit-template). It includes files to install dependencies via pip or conda.
+
+### via pip in an existing Python environment
+
+To install all required depdencies via pip in an already existing Python environment, run the following command in the terminal:
+
+`pip install -r requirements.txt`
+
+### create new environment via conda/mamba
+
+Create and activate the conda environment:
+
+`conda env create -f environment.yml`
+
+`conda activate streamlit-env`
+
+### run the app
+
+Run the app via streamlit command in the terminal with or without *local* mode (default is *online* mode). Learn more about *local* and *online* mode in the documentation page 📖 **OpenMS Template App**.
+
+`streamlit run app.py [local]`
+
+## Docker
+
+This repository contains two Dockerfiles.
+
+1. `Dockerfile`: This Dockerfile builds all dependencies for the app including Python packages and the OpenMS TOPP tools. Recommended for more complex workflows where you want to use the OpenMS TOPP tools for instance with the **TOPP Workflow Framework**.
+2. `Dockerfile_simple`: This Dockerfile builds only the Python packages. Recommended for simple apps using pyOpenMS only.
+
+""")

pages/1_📖_User_Guide.py

@@ -0,0 +1,8 @@
+import streamlit as st 
+from src.common import page_setup
+
+page_setup()
+
+st.markdown("""
+# User Guide   
+""")

pages/2_📖_Build_App.py

@@ -0,0 +1,76 @@
+import streamlit as st 
+
+from src.common import page_setup
+
+page_setup()
+
+st.markdown("""
+# Build your own app based on this template
+
+## Key concepts
+
+**Workspaces** 
+
+Directories where all data generated and uploaded can be stored as well as a workspace specific parameter file.
+
+**Run the app locally and online**
+
+Launching the app with the `local` argument let's the user create/remove workspaces. In the online the user gets a workspace with a specific ID.
+
+**Parameters**
+
+Parameters (defaults in `assets/default-params.json`) store changing parameters for each workspace. Parameters are loaded via the page_setup function at the start of each page. To track a widget variable via parameters simply give them a key and add a matching entry in the default parameters file. Initialize a widget value from the params dictionary.
+
+```python
+params = page_setup()
+
+st.number_input(label="x dimension", min_value=1, max_value=20,
+value=params["example-y-dimension"], step=1, key="example-y-dimension")
+
+save_params()
+```
+
+## Code structure
+
+- **Pages** must be placed in the `pages` directory.
+- It is recommended to use a separate file for defining functions per page in the `src` directory.
+- The `src/common.py` file contains a set of useful functions for common use (e.g. rendering a table with download button).
+
+## App layout
+
+- Main page contains explanatory text on how to use the app and a workspace selector.
+- Sidebar contains the OpenMS logo, settings panel and a workspace indicator. The main page contains a workspace selector as well.
+- See pages in the template app for example use cases. The content of this app serves as a documentation.
+
+## Modify the template to build your own app
+
+- in `src/common.py` update the name of your app and the repository name
+- in `clean-up-workspaces.py` update the name of the workspaces directory to `/workspaces-<your-repository-name>`
+    - e.g. for the streamlit template it's "/workspaces-streamlit-template"
+- chose one of the Dockerfiles depending on your use case:
+    - `Dockerfile` build OpenMS including TOPP tools
+    - `Dockerfile_simple` uses pyOpenMS only
+- update the Dockerfile:
+    - with the `GITHUB_USER` owning the streamlit app repository
+    - with the `GITHUB_REPO` name of the streamlit app repository
+    - if your main streamlit file is not called `app.py` modfify the following line
+        - `RUN echo "mamba run --no-capture-output -n streamlit-env streamlit run app.py" >> /app/entrypoint.sh`
+- update Python package dependency files:
+    - `requirements.txt` if using `Dockerfile_simple`
+    - `environment.yml` if using `Dockerfile`
+- update `README.md`
+- for the Windows executable package:
+    - update `datas` in `run_app_temp.spec` with the Python packages required for your app
+    - update main streamlit file name to run in `run_app.py`
+    
+## How to build a workflow
+
+### Simple workflow using pyopenms
+
+Take a look at the example pages `Simple Workflow` or `Workflow with mzML files` for examples. Put streamlit logic inside the pages and call the functions with workflow logic from from the `src` directory (for our examples `src/simple_workflow.py` and `src/mzmlfileworkflow.py`).
+
+### Complex workflow using TOPP tools
+
+This template app features a module in `src/workflow` that allows for complex and long workflows to be built very efficiently. Check out the `TOPP Workflow Framework` page for more information.
+""")
+

pages/6_📖_TOPP-Workflow_Docs.py → pages/3_📖_TOPP_Workflow_Framework.py

@@ -10,7 +10,7 @@
 
 wf = Workflow()
 
-st.title("📖 Workflow Framework Docs")
+st.title("📖 TOPP Workflow Framework Documentation")
 
 st.markdown(
 """

pages/4_📖_Deployment.py

@@ -0,0 +1,15 @@
+import streamlit as st 
+import requests
+
+from src.common import page_setup
+
+page_setup()
+
+url = "https://raw.githubusercontent.com/OpenMS/streamlit-deployment/main/README.md"
+
+response = requests.get(url)
+
+if response.status_code == 200:
+    st.markdown(response.text)  # or process the content as needed
+else:
+    st.warning("Failed to get README from streamlit-deployment repository.")