Add workflow for deploying the docs

Author: giordano

.github/workflows/Documentation.yml

@@ -0,0 +1,117 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags: "*"
+    paths:
+      - ".github/workflows/Documentation.yml"
+      - "docs/**"
+      - "src/**"
+      - "Project.toml"
+  pull_request:
+    paths:
+      - ".github/workflows/Documentation.yml"
+      - "docs/**"
+      - "src/**"
+      - "Project.toml"
+  release:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: always.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: "1.12"
+      - uses: julia-actions/cache@v2
+        id: julia-cache
+      - name: Instantiate docs environment
+        shell: julia --color=yes --project=docs {0}
+        run: |
+          using Pkg
+          Pkg.instantiate()
+      - name: Build documentation
+        run:
+          julia --color=yes --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Save Julia depot cache on cancel or failure
+        id: julia-cache-save
+        if: cancelled() || failure()
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ${{ steps.julia-cache.outputs.cache-paths }}
+          key: ${{ steps.julia-cache.outputs.cache-key }}
+      - uses: actions/upload-artifact@v5
+        with:
+          name: documentation-build
+          path: docs/build
+          retention-days: 10
+
+  deploy-docs:
+    # Deploy docs only if triggers is not a PR, or a PR not from a fork.
+    if: ${{ (github.event_name != 'pull_request') || (! github.event.pull_request.head.repo.fork) }}
+    needs: build-docs
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    concurrency:
+      # Have only one job pushing the docs at a time.
+      group: docs-pushing
+    steps:
+      - uses: actions/checkout@v6
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: "1.12"
+      - uses: julia-actions/cache@v2
+        id: julia-cache
+      - uses: actions/download-artifact@v6
+        with:
+          name: documentation-build
+          path: docs/build
+      - name: Remove extra files
+        # There may be JLD2 files generated during execution of Literate
+        # examples, we don't need them on the website.
+        run:
+          rm -fv docs/build/literated/*.jld2
+      - name: Instantiate docs environment
+        shell: julia --color=yes {0}
+        run: |
+          # We only need `Documenter` for publishing the docs, let's not
+          # reinstall the world all over again.
+          using Pkg
+          Pkg.add(; name="Documenter", version="1")
+      - name: Deploy documentation
+        run:
+          julia --color=yes docs/deploy.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+      - name: Save Julia depot cache on cancel or failure
+        id: julia-cache-save
+        if: cancelled() || failure()
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ${{ steps.julia-cache.outputs.cache-paths }}
+          key: ${{ steps.julia-cache.outputs.cache-key }}

docs/deploy.jl

@@ -0,0 +1,9 @@
+using Documenter
+
+deploydocs(;
+    repo="github.com/JuliaTesting/ParallelTestRunner.jl",
+    devbranch="main",
+    # Only push previews if all the relevant environment variables are non-empty. This is an
+    # attempt to work around https://github.com/JuliaDocs/Documenter.jl/issues/2048.
+    push_preview = all(!isempty, (get(ENV, "GITHUB_TOKEN", ""), get(ENV, "DOCUMENTER_KEY", ""))),
+)

docs/make.jl

@@ -17,9 +17,3 @@ makedocs(;
         "API Reference" => "api.md",
     ],
 )
-
-deploydocs(;
-    repo="github.com/JuliaTesting/ParallelTestRunner.jl",
-    devbranch="main",
-)
-