Merge pull request #20 from ogrisel/preview-doc-setup

Initial workflow config for doc previews on netlify

.github/workflows/pr_doc_preview.yml

@@ -0,0 +1,66 @@
+name: Preview doc in PRs
+
+on:
+  workflow_run:
+    workflows: ["push_doc"]
+    types:
+      - completed
+
+jobs:
+  pr_doc_preview:
+    runs-on: ubuntu-latest
+    if: ${{github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'}}
+    steps:
+      - name: 'Commit Status: Set Workflow Status as Pending'
+        uses: myrotvorets/set-commit-status-action@1.1.6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: pending
+          sha: ${{ github.event.workflow_run.head_sha }}
+          context: 'Doc preview'
+
+      - uses: dawidd6/action-download-artifact@v2
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          workflow: push_doc.yml
+          run_id: ${{ github.event.workflow_run.id }}
+          name: doc-preview
+
+      - name: Get pull request number
+        id: pull-request-number
+        run: |
+          export PULL_REQUEST_NUMBER=`cat pull_request_number`
+          echo "PULL_REQUEST_NUMBER=$PULL_REQUEST_NUMBER"
+          echo "result=${PULL_REQUEST_NUMBER}" >> $GITHUB_OUTPUT
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+      - run: npm install --global netlify-cli@6
+      - name: Deploy to Netlify
+        # The github secrets hold a Personal Access Token (PAT) managed by
+        # ogrisel on Netlify. I should allow to programmatically upload doc
+        # previews under the hazardous-doc.netlify.app domain.
+        env:
+          NETLIFY_SITE_ID: hazardous-doc
+          NETLIFY_AUTH_TOKEN: ${{secrets.NETLIFY_AUTH_TOKEN}}
+        run: |
+          echo "Deploying PR ${{steps.pull-request-number.outputs.result}} to Netlify"
+          netlify deploy --dir=build --alias=pull-request-${{steps.pull-request-number.outputs.result}}
+
+      - name: 'Commit Status: Update deployment status'
+        uses: myrotvorets/set-commit-status-action@1.1.6
+        # Always run this step regardless of job failing early
+        if: always()
+        env:
+          DEPLOY_SUCCESS: Successfully deployed preview.
+          DEPLOY_FAILURE: Failed to deploy preview.
+          TARGET_URL_SUCCESS: https://pull-request-${{steps.pull-request-number.outputs.result}}--hazardous-doc.netlify.app/
+          TARGET_URL_FAILURE: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: ${{ job.status == 'success' && 'success' || 'failure' }}
+          sha: ${{ github.event.workflow_run.head_sha }}
+          context: 'Doc preview'
+          description: ${{ job.status == 'success' && env.DEPLOY_SUCCESS || env.DEPLOY_FAILURE }}
+          targetUrl:  ${{ job.status == 'success' && env.TARGET_URL_SUCCESS || env.TARGET_URL_FAILURE }}

.github/workflows/push_doc.yml

@@ -1,28 +1,54 @@
-name: Publish documentation
+name: Build documentation
 
 on:
   push:
     branches:
       - main
-  workflow_dispatch:
+      - test-ci*
+  pull_request:
+    branches:
+      - main
 
 permissions:
   contents: write
 
 jobs:
-  deploy:
+  push_doc:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
+
       - uses: actions/setup-python@v4
         with:
           python-version: '3.10'
+
       - run: pip install .[doc]
+
       - name: Sphinx build
         run: sphinx-build doc build
+
+      - name: Save the PR number
+        env:
+          GITHUB_PULL_REQUEST_NUMBER: ${{github.event.number}}
+        run: |
+          echo "Storing PR number ${{github.event.number}} to 'pull_request_number' file"
+          echo ${{github.event.number}} > pull_request_number
+
+      - name: Upload doc preview
+        # The publication of the preview itself happens in pr-doc-preview.yml
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: doc-preview
+          path: |
+            ./build
+            pull_request_number
+
       - name: Deploy
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
         uses: peaceiris/actions-gh-pages@v3
         with:
           publish_branch: gh-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./build
+          commit_message: "[ci skip] ${{ github.event.head_commit.message }}"