Feat: Build Docs Preview on PR

.github/workflows/docs-pr-cleanup.yml

@@ -0,0 +1,55 @@
+name: Docs - PR Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+env:
+  GIT_COMMITTER_NAME: github-actions[bot]
+  GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
+  GIT_AUTHOR_NAME: github-actions[bot]
+  GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
+
+concurrency:
+  group: "pages-pr"
+  cancel-in-progress: true
+
+jobs:
+  remove-preview-files:
+    runs-on: ubuntu-latest
+    outputs:
+      hash: ${{ steps.commit.outputs.hash }}
+    permissions:
+      contents: write
+    concurrency:
+      group: deploy
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - name: Remove Preview
+        run: |
+          git rm -rf pr/${{ github.event.number }}
+
+      - name: Commit and Push
+        id: commit
+        run: |
+          git commit \
+            -m "Remove Preview for PR#${{ github.event.number }}" \
+            -m "${{ github.event.pull_request.head.sha }}"
+          git push
+          echo "hash=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
+
+  comment-closed:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    needs: remove-preview-files
+    steps:
+      - uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          append: true
+          message: |
+            Preview removed on merge/PR close with ${{ needs.remove-preview-files.outputs.hash }}

.github/workflows/docs-pr.yml

@@ -0,0 +1,73 @@
+name: Docs - PR
+
+on:
+  pull_request:
+
+env:
+  GIT_COMMITTER_NAME: github-actions[bot]
+  GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
+  GIT_AUTHOR_NAME: github-actions[bot]
+  GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
+
+concurrency:
+  group: "pages-pr--${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  build-and-upload:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/setup
+        with:
+          python-version: 3.8
+
+      - run: poetry run poe docs build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          path: ./site
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build-and-upload
+    permissions:
+      contents: write
+    concurrency:
+      group: deploy
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - uses: actions/download-artifact@v4
+
+      - name: Add/Update Preview
+        run: |
+          mkdir -p pr
+          rm -rf pr/${{ github.event.number }}
+          mv artifact pr/${{ github.event.number }}
+
+      - name: Commit and Push
+        run: |
+          git add --all pr/${{ github.event.number }}
+          git clean -fdx
+          git commit \
+            -m "Preview for PR#${{ github.event.number }}" \
+            -m "${{ github.event.pull_request.head.sha }}"
+          git push
+
+  comment:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    env:
+      url: https://${{ github.repository_owner }}.github.io/${{github.event.repository.name}}/pr/${{ github.event.number }}
+    needs: deploy
+    steps:
+      - uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          message: |
+            View preview here - ${{ env.url }} (build for ${{ github.event.pull_request.head.sha }})

.github/workflows/docs.yml

@@ -1,15 +1,22 @@
-name: Build and Deploy Documentation
+name: Docs
 
 on:
   push:
     branches:
       - main
 
-permissions:
-  contents: write
+env:
+  GIT_COMMITTER_NAME: github-actions[bot]
+  GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
+  GIT_AUTHOR_NAME: github-actions[bot]
+  GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
 
 jobs:
-  deploy:
+  build-and-upload:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -18,11 +25,49 @@ jobs:
         with:
           python-version: 3.8
 
-      - run: poetry run poe docs gh-deploy --force
+      - run: poetry run poe docs build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          path: ./site
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build-and-upload
+    permissions:
+      contents: write
+    concurrency:
+      group: deploy
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - name: Clean
+        run: |
+          rm -rf *
+          git checkout -- pr || true
+          git status -sb
+
+      - uses: actions/download-artifact@v4
+
+      - name: Update
+        run: |
+          mv artifact/* .
+          git status -sb
+
+      - name: Commit and Push
+        run: |
+          git add --all .
+          git clean -fdx
+          git commit -m "Update documentation for ${{ github.sha }}"
+          git push
 
   rtd_webhook:
     runs-on: ubuntu-latest
     needs: deploy
+    if: github.repository_owner == 'European-XFEL'
     steps:
       - name: Trigger RTD User Documentation Webhook
         run: curl -X POST ${{ secrets.RTD_USER_DOCS_WEBHOOK_URL }} -d 'token=${{ secrets.RTD_USER_DOCS_WEBHOOK_SECRET }}'

docs/maintenance/ci-cd.md

@@ -0,0 +1,35 @@
+# CI/CD
+
+## Documentation
+
+The documentation is hosted with GitHub Pages, configured to deploy the contents of the `gh-pages` branch as a statically hosted web page.
+
+There are two main workflows that are used to update the documentation:
+
+1. `.github/workflows/docs.yml` - triggered on pushes to `main`, this will build the static site and push it to the `gh-pages` branch.
+2. `.github/workflows/docs-pr.yml` - triggered on pull requests, this will build the static site, add it to a subdirectory `pr/<PR_NUMBER>`, and comment on the PR with a link to the preview. When the PR is closed, the directory is deleted.
+3. `.github/workflows/docs-pr-cleanup.yml` - triggered on pull request close or merge, this will delete the preview directory.
+
+### EuXFEL User Documentation Integration
+
+The user documentation is hosted on EuXFEL RTD, it is 'integrated' with the environments documentation by including this repository as a submodule, which is then built as part of the user documentation build process.
+
+To keep the two in sync, when the documentation is updated (merge/push to `main`) it triggers a RTD webhook to rebuild the user documentation, which will pull the latest version of the submodule.
+
+For more information see:
+
+- <https://github.com/European-XFEL/environments/pull/24>
+- <https://git.xfel.eu/dataAnalysis/user-documentation/-/merge_requests/107>
+
+## Package Builds
+
+!!! warning "Work in Progress"
+
+    Some work done in:
+
+    - https://github.com/European-XFEL/environments/pull/30
+    - https://github.com/European-XFEL/environments/tree/feat/build-pkg-ci
+
+## Environment Builds
+
+!!! warning "Work in Progress"

mkdocs.yml

@@ -42,6 +42,7 @@ nav:
       - Environment Management: "maintenance/environments.md"
       - Recipe Creation: "maintenance/recipes.md"
       - Conda Installations: "maintenance/instances.md"
+      - CI/CD: "maintenance/ci-cd.md"
   - Citing: "citing.md"
 
 plugins: