docs: modernize theme, automate deployment, refresh content

.github/workflows/docs.yml

@@ -0,0 +1,90 @@
+name: Deploy Documentation
+
+# Publishes versioned docs to the gh-pages branch with mike.
+#   - a GitHub release  -> deploy that version and move the `latest` alias
+#   - a push to main     -> deploy the floating `dev` version (unreleased docs)
+#   - manual dispatch    -> deploy an arbitrary version/alias (safe for testing)
+#
+# GitHub Pages for this repo serves "from a branch" (gh-pages); mike commits and
+# pushes the built site there, and Pages rebuilds automatically. This is NOT the
+# actions/deploy-pages OIDC flow, so the only permission needed is contents:write.
+on:
+  release:
+    types: [published]
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "themap/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version identifier to deploy (e.g. 0.5.0 or test)"
+        required: true
+        default: "test"
+      alias:
+        description: "Alias to point at this version (leave blank for none)"
+        required: false
+        default: ""
+
+# Serialize deploys: they all mutate the single gh-pages branch, and concurrent
+# pushes would race and reject. Do not cancel in-flight deploys (a half-finished
+# mike push could leave gh-pages inconsistent) — queue them instead.
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      # mike pushes the built site to the gh-pages branch.
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # mike needs full history and the gh-pages branch; a shallow clone
+          # breaks versioned deploys.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Install dependencies
+        run: uv pip install --system -e ".[docs]"
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy released version
+        if: github.event_name == 'release'
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          mike deploy --push --update-aliases "$VERSION" latest
+          mike set-default --push latest
+
+      - name: Deploy dev docs from main
+        if: github.event_name == 'push'
+        run: mike deploy --push dev
+
+      - name: Deploy manual dispatch
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if [ -n "${{ inputs.alias }}" ]; then
+            mike deploy --push --update-aliases "${{ inputs.version }}" "${{ inputs.alias }}"
+          else
+            mike deploy --push "${{ inputs.version }}"
+          fi

docs/assets/css/custom-splito.css → docs/assets/css/themap.css

@@ -14,11 +14,20 @@
 }
 
 [data-md-color-scheme="slate"] {
+  /* Lighter purple in dark mode so header text and links keep AA contrast. */
+  --md-primary-fg-color: #b39ddb;
+  --md-primary-fg-color--light: #d1c4e9;
+  --md-primary-fg-color--dark: #9575cd;
+  --md-accent-fg-color: #b388ff;
   --md-code-bg-color: #1e1e2e;
   --md-default-bg-color: #0d1117;
 }
 
 /* ===== Typography ===== */
+.md-typeset {
+  line-height: 1.7;
+}
+
 .md-typeset h1 {
   font-weight: 700;
   letter-spacing: -0.02em;
@@ -27,9 +36,9 @@
 
 .md-typeset h2 {
   font-weight: 600;
-  margin-top: 2rem;
-  padding-bottom: 0.5rem;
-  border-bottom: 2px solid var(--md-primary-fg-color--light);
+  margin-top: 2.5rem;
+  padding-bottom: 0.3rem;
+  border-bottom: 1px solid var(--md-default-fg-color--lightest);
 }
 
 .md-typeset h3 {
@@ -67,11 +76,11 @@
 /* ===== Navigation ===== */
 .md-nav__title {
   font-weight: 600;
-  font-size: 0.75rem;
+  font-size: 0.8rem;
 }
 
 .md-nav__link {
-  font-size: 0.8rem;
+  font-size: 0.85rem;
 }
 
 .md-nav__item {
@@ -85,7 +94,7 @@
 
 /* Right-side table of contents */
 .md-nav--secondary .md-nav__link {
-  font-size: 0.75rem;
+  font-size: 0.8rem;
 }
 
 /* Tab navigation styling */
@@ -105,7 +114,7 @@
   overflow: hidden;
   box-shadow: 0 1px 4px rgba(0, 0, 0, 0.08);
   border: 1px solid rgba(0, 0, 0, 0.08);
-  font-size: 0.85rem;
+  font-size: 0.9rem;
 }
 
 .md-typeset table:not([class]) th {
@@ -116,6 +125,12 @@
   text-align: left;
 }
 
+/* In dark mode the primary is a light purple; use a darker header tone so the
+   white header text keeps contrast. */
+[data-md-color-scheme="slate"] .md-typeset table:not([class]) th {
+  background: var(--md-primary-fg-color--dark);
+}
+
 .md-typeset table:not([class]) td {
   padding: 0.65rem 1rem;
   border-bottom: 1px solid rgba(0, 0, 0, 0.05);
@@ -165,17 +180,17 @@
 
 /* ===== Footer ===== */
 .md-footer {
-  background: linear-gradient(135deg, var(--themap-gradient-start), var(--themap-gradient-end));
+  background-color: var(--md-primary-fg-color--dark);
 }
 
 .md-footer-meta {
-  background: rgba(0, 0, 0, 0.15);
+  background: rgba(0, 0, 0, 0.2);
 }
 
 /* ===== Header ===== */
 .md-header {
-  background: linear-gradient(90deg, var(--themap-gradient-start), var(--themap-gradient-end));
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  background-color: var(--md-primary-fg-color);
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.12);
 }
 
 /* ===== Search ===== */
@@ -196,8 +211,8 @@
 }
 
 .md-typeset a.md-button--primary {
-  background: linear-gradient(135deg, var(--themap-gradient-start), var(--themap-gradient-end));
-  border: none;
+  background: var(--md-primary-fg-color);
+  border-color: var(--md-primary-fg-color);
 }
 
 /* ===== API Documentation ===== */
@@ -222,7 +237,7 @@
 
 /* ===== Content Width ===== */
 .md-content__inner {
-  max-width: 900px;
+  max-width: 54rem;
 }
 
 /* ===== Version Selector ===== */

docs/index.md

@@ -1,5 +1,14 @@
 # THEMAP: Task Hardness Estimation for Molecular Activity Prediction
 
+[![DOI](https://img.shields.io/badge/DOI-10.1021%2Facs.jcim.4c00160-blue)](https://doi.org/10.1021/acs.jcim.4c00160)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://badge.fury.io/py/themap.svg)](https://pypi.org/project/themap/)
+
+<p align="center">
+  <img src="assets/images/banner.png" alt="THEMAP banner" style="max-width:100%;">
+</p>
+
 **THEMAP** is a Python library for computing distances between chemical datasets and estimating task hardness for bioactivity prediction. It helps researchers identify similar tasks for transfer learning and quantify prediction difficulty.
 
 <div class="grid cards" markdown>
@@ -41,18 +50,23 @@
 ## Installation
 
 ```bash
-# Clone and install (uv-based)
-git clone https://github.com/HFooladi/THEMAP.git
-cd THEMAP
-source install.sh
+# From PyPI (recommended)
+pip install themap
+
+# With all optional dependencies (ML, protein, OTDD)
+pip install "themap[all]"
+```
 
-# Or install with pip
-pip install -e .
+To install from source for development:
 
-# With all optional dependencies
-pip install -e ".[all]"
+```bash
+git clone https://github.com/HFooladi/THEMAP.git
+cd THEMAP
+source install.sh   # uv-based; creates .venv and installs dev extras
 ```
 
+See [Getting Started](user-guide/getting-started.md) for the optional dependency groups.
+
 ## Quick Examples
 
 ### Command Line