haddocking · sverhoeven · Mar 17, 2026
diff --git a/README.md b/README.md
@@ -87,8 +87,8 @@ The main entry point is the `protein-quest` command line tool which has multiple
 subcommands to perform actions.
 
 To use programmaticly, see the
-[Jupyter notebooks](https://www.bonvinlab.org/protein-quest/notebooks) and
-[API documentation](https://www.bonvinlab.org/protein-quest/autoapi/protein_quest/).
+[Jupyter notebooks](https://www.bonvinlab.org/protein-quest/notebooks/README.html),
+and [API documentation](https://www.bonvinlab.org/protein-quest/autoapi/protein_quest/).
 
 While downloading or copying files it uses a global cache (located at
 `~/.cache/protein-quest`) and hardlinks to save disk space and improve speed.

diff --git a/docs/notebooks/README.md b/docs/notebooks/README.md
@@ -0,0 +1,67 @@
+# Notebooks
+
+Jupyter notebooks show how to use protein-quest through its Python API and can be
+run locally or in cloud notebook environments.
+
+## Avalable notebooks
+
+| Notebook | What you will do |
+| --- | --- |
+| [Search UniProt](uniprot.ipynb) | Find UniProt accessions and map them to PDB, AlphaFold, EMDB, and partner datasets. |
+| [AlphaFold](alphafold.ipynb) | Download AlphaFold models, filter on confidence, and visualize structures with Mol*. |
+| [PDBe](pdbe.ipynb) | Download PDBe structures, extract single chains, and visualize structures with Mol*. |
+
+## Launch in cloud environments
+
+Use the links below to open each notebook quickly.
+
+| Notebook | Google Colab | notebooks.egi.eu | Binder | nbgitpuller |
+| --- | --- | --- | --- | --- |
+| Search UniProt | [Open](https://colab.research.google.com/github/haddocking/protein-quest/blob/main/docs/notebooks/uniprot.ipynb) | [Open hub](https://notebooks.egi.eu/hub/) | [Open](https://mybinder.org/v2/gh/haddocking/protein-quest/HEAD?urlpath=lab/tree/docs/notebooks/uniprot.ipynb) | [Generate link](https://nbgitpuller.readthedocs.io/en/latest/link.html?hub=https://notebooks.egi.eu&repo=https://github.com/haddocking/protein-quest&branch=main) |
+| AlphaFold | [Open](https://colab.research.google.com/github/haddocking/protein-quest/blob/main/docs/notebooks/alphafold.ipynb) | [Open hub](https://notebooks.egi.eu/hub/) | [Open](https://mybinder.org/v2/gh/haddocking/protein-quest/HEAD?urlpath=lab/tree/docs/notebooks/alphafold.ipynb) | [Generate link](https://nbgitpuller.readthedocs.io/en/latest/link.html?hub=https://notebooks.egi.eu&repo=https://github.com/haddocking/protein-quest&branch=main) |
+| PDBe | [Open](https://colab.research.google.com/github/haddocking/protein-quest/blob/main/docs/notebooks/pdbe.ipynb) | [Open hub](https://notebooks.egi.eu/hub/) | [Open](https://mybinder.org/v2/gh/haddocking/protein-quest/HEAD?urlpath=lab/tree/docs/notebooks/pdbe.ipynb) | [Generate link](https://nbgitpuller.readthedocs.io/en/latest/link.html?hub=https://notebooks.egi.eu&repo=https://github.com/haddocking/protein-quest&branch=main) |
+
+<!-- TODO test links -->
+
+## Notes
+
+- Google Colab and Binder open notebooks directly from this repository.
+- notebooks.egi.eu requires sign-in and VO enrollment before use.
+- nbgitpuller links depend on a JupyterHub where nbgitpuller is installed.
+
+This section explains how to run notebooks locally.
+
+## Local setup
+
+1. Install Jupyter.
+
+```bash
+python -m pip install jupyterlab
+```
+
+2. Install notebook dependencies.
+
+For the released package:
+
+```bash
+python -m pip install protein-quest[nb]
+```
+(The `[nb]` extra installs `ipymolstar` for structure visualization in the AlphaFold and PDBe notebooks.)
+
+3. Start Jupyter and open a notebook.
+
+```bash
+jupyter lab
+```
+
+Then open one of the notebooks (*.ipynb files).
+
+## Runtime dependencies
+
+The first code cell in each notebook installs required packages, including
+`protein-quest` and `ipymolstar`.
+
+- Google Colab: best for quick exploration.
+- Binder: no local install needed, startup can take a few minutes.
+- notebooks.egi.eu: requires EGI account and VO enrollment.
+- nbgitpuller: requires a JupyterHub deployment with nbgitpuller installed.
diff --git a/docs/notebooks/alphafold.ipynb b/docs/notebooks/alphafold.ipynb
diff --git a/docs/notebooks/index.md b/docs/notebooks/index.md
diff --git a/docs/notebooks/pdbe.ipynb b/docs/notebooks/pdbe.ipynb
diff --git a/docs/notebooks/uniprot.ipynb b/docs/notebooks/uniprot.ipynb
@@ -1,5 +1,27 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "dd5fcc71",
+   "metadata": {},
+   "source": [
+    "## Environment setup\n",
+    "\n",
+    "Run the next cell once per fresh kernel to install notebook dependencies.\n",
+    "If you install packages in the active kernel, restart the kernel and rerun all cells."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9ae26858",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cloud and local notebooks: install required runtime dependencies.\n",
+    "!pip install -q protein-quest[nb]"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "4ef4bfbe",

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -78,7 +78,7 @@ nav:
   - CLI Reference: cli.md
   - FAQ: faq.md
   - Notebooks:
-      - notebooks/index.md
+      - Overview: notebooks/README.md
       - Search uniprot: notebooks/uniprot.ipynb
       - Alphafold: notebooks/alphafold.ipynb
       - PDBe: notebooks/pdbe.ipynb

diff --git a/pyproject.toml b/pyproject.toml
@@ -63,6 +63,10 @@ mcp = [
     "fastmcp>=2.11.3",
     "pydantic>=2.12.0",
 ]
+nb = [
+    "molviewspec>=1.8.1",
+]
+
 
 [dependency-groups]
 type = [

diff --git a/uv.lock b/uv.lock