ci: Separate document deployment from pull request checks

Separate the task of checking document links and building them
from the deployment to GitHub Pages.

The GitHub Actions runner lacks the necessary privileges to deploy
the documentation during pull requests, which caused link checking
errors.

Author: fraya

.github/workflows/build-docs.yml renamed to .github/workflows/build-and-deploy-docs.yml

@@ -1,14 +1,10 @@
-name: Build documentation
+name: Build and deploy docs
 
 on:
   push:
     # all branches
     paths:
       - 'documentation/**'
-  pull_request:
-    # all branches
-    paths:
-      - 'documentation/**'
 
   # This enables the Run Workflow button on the Actions tab.
   workflow_dispatch:

.github/workflows/check-docs.yml

@@ -0,0 +1,42 @@
+name: Check documentation
+
+on:
+  pull_request:
+    # all branches
+    paths:
+      - 'documentation/**'
+
+  # This enables the Run Workflow button on the Actions tab.
+  workflow_dispatch:
+
+# https://github.com/JamesIves/github-pages-deploy-action#readme
+permissions:
+    contents: write
+
+# Set DYLAN environment variable to GITHUB_WORKSPACE so packages are
+# installed in ../../_packages relative to documentation's Makefile
+env:
+  DYLAN: ${{ github.workspace }}
+
+jobs:
+
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check links
+        uses: addnab/docker-run-action@v3
+        with:
+          image: ghcr.io/fraya/dylan-docs
+          options: -v ${{ github.workspace }}/documentation:/docs
+          run: make linkcheck
+
+      - name: Build docs with Furo theme
+        uses: addnab/docker-run-action@v3
+        with:
+          image: ghcr.io/fraya/dylan-docs
+          options: -v ${{ github.workspace }}/documentation:/docs
+          run: make html