ci: add preview support

This is experimental

Author: gnikit

.github/workflows/delete_preview.yml

@@ -0,0 +1,43 @@
+# Github action to cleanup a PR preview
+# Runs when a pull request is merged or comment contains '#delete_preview'
+#
+
+name: PR Preview Cleanup
+
+on:
+  issue_comment:
+    types: [created]
+
+  pull_request:
+    types:
+      - closed
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.merged == true || contains(github.event.comment.body, '#delete-preview')
+
+    steps:
+      # Checkout existing gh-pages branch into PUBLISH_DIR
+      - name: Checkout gh-pages
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      # Cleanup preview files
+      - name: PR Cleanup
+        run: rm -rf pr/${{github.event.issue.number}}
+
+      - name: Commit and push to gh-pages
+        uses: EndBug/[email protected]
+        with:
+          message: "Sphinx build cleanup pr/${{github.event.issue.number}}"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Comment on pull request
+      - name: Comment on pull request
+        uses: peter-evans/create-or-update-comment@v2
+        with:
+          issue-number: ${{github.event.issue.number}}
+          body: The preview build for this PR has now been deleted.

.github/workflows/preview.yml

@@ -0,0 +1,57 @@
+# Github action to build preview sphinx site and commit to gh-pages branch
+#  Built site is pushed to 'gh-pages' branch
+#
+
+name: Sphinx Preview Build
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.event.issue.pull_request && contains(github.event.comment.body, '#preview')
+
+    steps:
+      - name: Checkout pr/${{github.event.issue.number}}
+        uses: actions/checkout@v3
+
+      - name: Fetch pr/${{github.event.issue.number}}
+        run: |
+          git fetch origin pull/${{github.event.issue.number}}/head:pr-${{github.event.issue.number}}
+          git checkout pr-${{github.event.issue.number}}
+
+      - name: Install dependencies
+        uses: mamba-org/provision-with-micromamba@main
+        with:
+          environment-file: environment.yaml
+
+      - name: Safe workflow for build preview
+        run: if [ -d "_build" ]; then rm -rf _build; fi
+
+      - name: Build page and Translations
+        if: contains(github.event.comment.body, '#preview')
+        run: |
+          make gettext html
+
+      - name: Create nojekyll file
+        run: |
+          touch _build/.nojekyll
+
+      - name: Deploy documentation sphinx
+        uses: JamesIves/[email protected]
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          target-folder: pr/${{github.event.issue.number}}
+          folder: _build/html
+          clean: false
+          git-config-email: [email protected]
+          git-config-name: Fortran
+
+      - name: Comment on pull request
+        uses: peter-evans/create-or-update-comment@v2
+        with:
+          issue-number: ${{github.event.issue.number}}
+          body: "This PR has been built with Sphinx and can be previewed at: https://fortran-lang.github.io/fpm/pr/${{github.event.issue.number}}"

README.md

@@ -118,3 +118,9 @@ msgstr "This is "
 
 After adding or updating translations
 build the documentation as described above.
+
+## Pull Requests Previews
+
+You can build the Preview of the fpm-docs website by opening a pull request
+and commenting `#preview` on the pull request. Similarly, you can force the
+deletion of the preview by commenting `#delete-preview`.