diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6575ecc..863874e 100644 --- a/.github/workflows/docs.yml +++ b/.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 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"