Publish the documentation to GitHub Pages

.github/workflows/docs.yml

@@ -6,6 +6,10 @@ on:
   pull_request:
     branches: [main, dev]
 
+# Default token scope; the deploy job overrides it with pages/id-token below.
+permissions:
+  contents: read
+
 jobs:
   build-docs:
     runs-on: ubuntu-latest
@@ -20,7 +24,28 @@ 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
+    # 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
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,14 +1,17 @@
 [![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
 
 ThermoScreening calculates thermochemical properties for molecular systems and provides a foundation for screening molecule sets. It currently supports thermochemistry workflows from DFTB+ inputs and exposes Python APIs for reading coordinates, parsing vibrational data, and running thermodynamic post-processing.
 
 ## 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]"

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/"

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"