From 31433f39eb51053898ae13dae6efce5d49076598 Mon Sep 17 00:00:00 2001
From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com>
Date: Mon, 6 Jul 2026 22:57:16 +0200
Subject: [PATCH 1/2] Publish the documentation to GitHub Pages

Deploy the Sphinx site to GitHub Pages on pushes to main. The docs job
now uploads a Pages artifact and a gated deploy-docs job (push to main
only) publishes it via actions/deploy-pages, so the previously
build-only docs are served at https://molarverse.github.io/ThermoScreening/.

Also set html_baseurl for canonical URLs, add a Documentation project URL
and a docs badge, and link the hosted site from the README.
---
 .github/workflows/docs.yml | 24 ++++++++++++++++++++++--
 README.md                  |  7 +++++--
 docs/conf.py               |  3 +++
 pyproject.toml             |  1 +
 4 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 6575ecc..07cb6fb 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -6,6 +6,10 @@ on:
   pull_request:
     branches: [main, dev]
 
+# Allow the deploy job to publish to GitHub Pages.
+permissions:
+  contents: read
+
 jobs:
   build-docs:
     runs-on: ubuntu-latest
@@ -20,7 +24,23 @@ jobs:
         run: python -m pip install -e ".[docs]"
       - name: Build the documentation
         run: python -m sphinx -b html docs docs/_build/html
-      - uses: actions/upload-artifact@v4
+      - name: Upload the Pages artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          name: docs-html
           path: docs/_build/html
+
+  # Publish the built docs to GitHub Pages on pushes to the default branch.
+  deploy-docs:
+    needs: build-docs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write       # to deploy to Pages
+      id-token: write    # to verify the deployment origin
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
index c62b7ef..162681f 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
 [![Python application](https://github.com/MolarVerse/ThermoScreening/actions/workflows/python-app.yml/badge.svg)](https://github.com/MolarVerse/ThermoScreening/actions/workflows/python-app.yml)
 [![codecov](https://codecov.io/gh/MolarVerse/ThermoScreening/graph/badge.svg?token=KhrG0zVZmS)](https://codecov.io/gh/MolarVerse/ThermoScreening)
+[![Docs](https://github.com/MolarVerse/ThermoScreening/actions/workflows/docs.yml/badge.svg)](https://molarverse.github.io/ThermoScreening/)
 
 # ThermoScreening
 
@@ -7,8 +8,10 @@ ThermoScreening calculates thermochemical properties for molecular systems and p
 
 ## Documentation
 
-Structured documentation (installation, usage, configuration, and the API
-reference) is built with Sphinx from the `docs/` directory:
+The documentation is published at **https://molarverse.github.io/ThermoScreening/**.
+
+It (installation, usage, configuration, and the API reference) is built with
+Sphinx from the `docs/` directory, and you can also build it locally:
 
 ```bash
 python -m pip install -e ".[docs]"
diff --git a/docs/conf.py b/docs/conf.py
index 1bb9011..0642178 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -35,3 +35,6 @@
 
 html_theme = "alabaster"
 html_static_path = []
+
+# Canonical location of the published documentation (GitHub Pages).
+html_baseurl = "https://molarverse.github.io/ThermoScreening/"
diff --git a/pyproject.toml b/pyproject.toml
index de48a4f..31bf9d7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -38,6 +38,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/MolarVerse/ThermoScreening"
+Documentation = "https://molarverse.github.io/ThermoScreening/"
 Repository = "https://github.com/MolarVerse/ThermoScreening"
 Issues = "https://github.com/MolarVerse/ThermoScreening/issues"
 

From 89d65580cf40073f3ff5f3793c2bce47b74dc0f7 Mon Sep 17 00:00:00 2001
From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com>
Date: Mon, 6 Jul 2026 22:59:58 +0200
Subject: [PATCH 2/2] Serialise Pages deploys, clarify permissions comment

Add a job-level concurrency group so overlapping main pushes queue
instead of racing the github-pages environment, and correct the
top-level permissions comment.
---
 .github/workflows/docs.yml | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 07cb6fb..863874e 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -6,7 +6,7 @@ on:
   pull_request:
     branches: [main, dev]
 
-# Allow the deploy job to publish to GitHub Pages.
+# Default token scope; the deploy job overrides it with pages/id-token below.
 permissions:
   contents: read
 
@@ -34,6 +34,11 @@ jobs:
     needs: build-docs
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    # Serialise deployments so overlapping main pushes don't race; let an
+    # in-flight deploy finish rather than cancelling it mid-publish.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     permissions:
       pages: write       # to deploy to Pages
       id-token: write    # to verify the deployment origin