docs: add webapp docs page (#327)

gcroci2 · CunliangGeng · web-flow · commit 01b918c71e42 · 2025-05-26T10:08:41.000+02:00
* add action for automatically deploy docs

* add webapp readme test file and point to it in the nav

* add readme from webapp

* improve and adapt readme

* ignore webapp readme

* add commands for docs build and deploy

* integrate make commands

* update docs with the new make cmds

* Update .github/workflows/deploy-docs.yml

Co-authored-by: Cunliang Geng &lt;c.geng@esciencecenter.nl&gt;

* rename sync command

---------

Co-authored-by: Cunliang Geng &lt;c.geng@esciencecenter.nl&gt;
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,40 @@
+name: Deploy documentation
+
+on:
+    workflow_dispatch:
+    release:
+      types:
+        - published
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout nplinker
+      uses: actions/checkout@v4
+      with:
+        ref: dev
+        fetch-tags: true
+
+    - name: Fetch gh-pages
+      run: git fetch origin gh-pages:gh-pages
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install dependencies
+      run: python3 -m pip install .[dev]
+
+    - name: Configure Git
+      run: |
+        git config user.email "${GITHUB_ACTOR_ID}+${GITHUB_ACTOR}@users.noreply.github.com"
+        git config user.name "GitHub Actions"
+        git config -l
+
+    - name: Sync webapp README and deploy docs
+      run: |
+        version=$(git describe --tags --abbrev=0 | sed -E 's/^v([0-9]+\.[0-9]+\.[0-9]+)-alpha\.([0-9]+)/\1a\2/')
+        make deploy-docs version=$version
diff --git a/.gitignore b/.gitignore
@@ -64,3 +64,6 @@ webapp/npapp/static/js/bokeh*.js
 src/nplinker/scoring/iokr/data/SPEC/
 tests/integration/data/nplinker_local_mode_example.zip
 strain_mappings.json
+
+# docs
+docs/webapp/readme.md
diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 # .PHONY is used to declare that the targets are not files
-.PHONY: install-dev clean clean-build clean-pyc clean-test clean-doc release build update-version
+.PHONY: install-dev clean clean-build clean-pyc clean-test clean-doc release build update-version sync-webapp-readme build-docs deploy-docs
 
 help:
 	@echo "Available commands to 'make':"
@@ -79,4 +79,17 @@ endif
 				-e 's/version: "$(CURRENT_VERSION)"/version: "$(NEW_VERSION)"/' $$file; \
 		fi; \
 	done
-	@echo "Version update complete."
+	@echo "Version update complete."
+
+sync-webapp-readme:
+	mkdir -p docs/webapp
+	curl -sSf https://raw.githubusercontent.com/NPLinker/nplinker-webapp/main/README.md -o docs/webapp/readme.md
+
+build-docs: sync-webapp-readme
+	mkdocs serve
+
+deploy-docs: sync-webapp-readme
+ifndef version
+	$(error version is not set. Usage: make deploy-docs version=YOUR_VERSION)
+endif
+	mike deploy -p -u $(version) latest
diff --git a/README.dev.md b/README.dev.md
@@ -132,22 +132,45 @@ mkdocs serve -w docs -w src
 Then open your browser and go to [http://127.0.0.1:8000/](http://127.0.0.1:8000/).
 
 ### Publishing the docs
-The docs are published on github pages. We use [mike](https://github.com/jimporter/mike)
-to deploy the docs to the `gh-pages` branch and to manage the versions of docs.
 
-For example, to deploy the version 2.0 of the docs to the `gh-pages` branch and make it the latest
-version, run:
-```shell
-mike deploy -p -u 2.0 latest
+Documentation is published to GitHub Pages using [mike](https://github.com/jimporter/mike), which also manages versioning on the `gh-pages` branch.
+
+#### Deploying a new version
+
+To deploy version `2.0` of the docs and mark it as the latest, run:
+
+```bash
+make deploy-docs version=2.0
+```
+
+This command does the following:
+
+* Fetches the latest README from the [`nplinker-webapp`](https://github.com/NPLinker/nplinker-webapp) repository.
+* Builds and deploys the documentation to the `gh-pages` branch.
+* Updates the `latest` alias to point to this version.
+* Creates a commit on the `gh-pages` branch to record the deployment.
+
+If you want to undo a deployment, you can run:
+
+```bash
+mike delete 2.0
 ```
-If you are not happy with the changes you can run `mike delete [version]`.
-All these mike operations will be recorded as git commits of branch `gh-pages`.
 
- `mike serve` is used to check all versions committed to branch `gh-pages`, which is for checking
- the production website. If you have changes but not commit them yet, you should use `mkdocs serve`
- instead of  `mike serve` to check them.
+#### Previewing the docs
+
+* To preview all committed versions from `gh-pages`, use:
+
+  ```bash
+  mike serve
+  ```
+
+* To preview your local, uncommitted changes, use:
 
+  ```bash
+  make build-docs
+  ```
 
+> `make build-docs` will also update the webapp README before serving the docs.
 
 ## Versioning
 
diff --git a/docs/webapp/readme.md b/docs/webapp/readme.md
@@ -0,0 +1,157 @@
+# NPLinker Web Application
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6875502.svg)](https://doi.org/10.5281/zenodo.6875502)
+
+👉 **[Webapp Live Demo](https://nplinker-webapp.onrender.com)**
+
+The [NPLinker](https://nplinker.github.io/nplinker/latest/) web application, built with [Plotly Dash](https://dash.plotly.com/), provides an interactive interface for visualizing NPLinker predictions.
+
+## Online Demo
+
+A live demo of the NPLinker webapp is automatically deployed to [Render](https://render.com/) from `main` branch.
+You can try out the webapp directly in your browser [here](https://nplinker-webapp.onrender.com).
+
+### Getting Started with Demo Data
+
+The webapp includes a convenient **"Load Demo Data"** button that automatically loads some sample data for you to try. Simply:
+
+1. Open the [live demo link](https://nplinker-webapp.onrender.com/)
+2. Click the **"Load Demo Data"** button below the file uploader
+3. The app will automatically download and process the sample dataset from [`tests/data/mock_obj_data.pkl`](https://github.com/NPLinker/nplinker-webapp/blob/main/tests/data/mock_obj_data.pkl)
+4. Start exploring natural product linking features!
+
+This demo web server is intended only for lightweight demo purposes. For full functionality, including large-scale data processing and persistent storage, please install the application locally or via Docker as described below.
+
+<details>
+<summary>⚠️ Demo Server Limitations</summary>
+
+<p>Please note the following limitations of the hosted demo:</p>
+
+<ul>
+  <li><strong>Cold start delay</strong>: Free-tier apps on Render sleep after 15 minutes of inactivity and may take 20–30 seconds to wake up.</li>
+  <li><strong>Performance</strong>: This is a minimal deployment on a free tier and is not optimized for large datasets or concurrent users.</li>
+  <li><strong>File size limits</strong>: The demo data button loads a small sample dataset suitable for testing. Uploading large datasets via the file uploader may lead to errors or timeouts.</li>
+  <li><strong>No persistent storage</strong>: Uploaded files are not saved between sessions.</li>
+</ul>
+
+</details>
+
+## Using the webapp
+
+### Input Data
+
+The webapp accepts data generated by NPLinker and saved as described in the [NPLinker quickstart section](https://nplinker.github.io/nplinker/latest/quickstart/). For testing purposes, a small sample dataset is provided in [`tests/data/mock_obj_data.pkl`](https://github.com/NPLinker/nplinker-webapp/blob/main/tests/data/mock_obj_data.pkl) that can be used to try out the webapp.
+
+Please note that links between genomic and metabolomic data must currently be computed using the NPLinker API separately, as this functionality is not yet implemented in the webapp (see [issue #19](https://github.com/NPLinker/nplinker-webapp/issues/19)). If no links are present in your data, the scoring table will be disabled.
+
+### Filtering Table Data
+
+The "Candidate Links" tables support data filtering to help you focus on relevant results. You can enter filter criteria directly into each column’s filter cell by hovering over the cell.
+
+For numeric columns like "Average Score" or "# Links":
+
+- `34.6` or `= 34.6` (exact match)
+- `> 30` (greater than)
+- `<= 50` (less than or equal to)
+
+For text columns like "BGC Classes" or "MiBIG IDs":
+
+- `Polyketide` or `contains Polyketide` (contains text)
+- `= Polyketide` (exact match)
+
+Multiple filters can be applied simultaneously across different columns to narrow down results.
+
+For a full list of supported filter operators, see the [official Plotly documentation](https://dash.plotly.com/datatable/filtering#filtering-operators).
+
+## Installation
+
+Before installing NPLinker webapp, ensure you have:
+
+- [Python ≥3.10](https://www.python.org/downloads/)
+- [Git](https://git-scm.com/downloads)
+- [Conda](https://docs.conda.io/en/latest/miniconda.html)
+
+You can install and run the NPLinker webapp in two ways: directly on your local machine or using Docker.
+
+### Option 1: Local Installation (using Conda)
+
+Follow these steps to install the application directly on your system:
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/NPLinker/nplinker-webapp.git
+   cd nplinker-webapp
+   ```
+
+2. **Set up a conda environment**
+   ```bash
+    # Create a new conda environment with Python 3.10
+    conda create -n nplinker-webapp python=3.10
+
+    # Activate the environment
+    conda activate nplinker-webapp
+   ```
+
+3. **Install dependencies**
+   ```bash
+   pip install -e .
+   ```
+
+4. **Run the application**
+   ```bash
+   python app/main.py
+   ```
+
+5. **Access the webapp**
+   
+   Open your web browser and navigate to `http://0.0.0.0:8050/`
+
+<details>
+<summary>Troubleshooting Local Installation</summary>
+
+<h4>Common issues and solutions</h4>
+
+<ul>
+  <li><strong>Port already in use</strong>: If port 8050 is already in use, modify the port in <code>app/main.py</code> by changing <code>app.run_server(debug=True, port=8050)</code></li>
+  <li><strong>Package installation errors</strong>: Make sure you're using Python 3.10 and that your pip is up-to-date</li>
+</ul>
+
+<p>If you encounter other problems, please check the <a href="https://github.com/NPLinker/nplinker-webapp/issues">Issues</a> page or create a new issue.</p>
+
+</details>
+
+### Option 2: Docker Installation
+
+Using Docker is the quickest way to get started with NPLinker webapp. Make sure you have [Docker](https://www.docker.com/) installed on your system before proceeding:
+
+1. **Pull the Docker image**
+   ```bash
+   docker pull ghcr.io/nplinker/nplinker-webapp:latest
+   ```
+
+2. **Run the container**
+   ```bash
+   docker run -p 8050:8050 ghcr.io/nplinker/nplinker-webapp:latest
+   ```
+
+3. **Access the webapp**
+   
+   Open your web browser and navigate to `http://0.0.0.0:8050/`
+
+<details>
+<summary>Docker Image Information</summary>
+
+<ul>
+  <li><strong>Available Tags</strong>:
+    <ul>
+      <li><code>latest</code>: The most recent build</li>
+      <li>Specific version tags based on GitHub releases</li>
+    </ul>
+  </li>
+
+  <li><strong>Performance Note</strong>: The application running in Docker might be slower than running it directly on your machine, depending on your Docker resource allocation settings. If you experience performance issues, consider increasing Docker's CPU and memory limits in your Docker Desktop settings, or use the local installation method.</li>
+
+  <li><strong>More Details</strong>: For additional information about the Docker image, see its <a href="https://github.com/NPLinker/nplinker-webapp/pkgs/container/nplinker-webapp">GitHub Container Registry page</a>.</li>
+</ul>
+
+</details>
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -102,6 +102,8 @@ nav:
     - Scoring Methods: api/scoring_methods.md
     - Data Models: api/scoring.md
     - Utilities: api/scoring_utils.md
+- Webapp:
+  - Webapp Docs: webapp/readme.md
 
 markdown_extensions:
 # https://python-markdown.github.io/extensions/
