Trac #31415: GH Actions workflow that builds documentation on each push

On each push to a branch in `sagemath/sagetrac-mirror`, it builds the
HTML documentation and, if this succeeds, deploys it to netlify for easy
inspection.
Example: https://62018055188ce050610e98a6--sagemath-tobias.netlify.app
Workflow runs: https://github.com/sagemath/sagetrac-
mirror/actions/workflows/doc-build.yml

Once this ticket is merged, I will add a badge pointing to the github
workflow (similar to the linting badge), where one then can get the url
for this particular deployment. Due to various open issues at netlify,
it is sadly not possible right now to set the deployment url to the
branch name so we use the commit hash for this.

For pushes to the develop branch it deploys the docs to the 'production'
website
https://sagemath-tobias.netlify.app/

I've chosen netlify (say over github pages) mainly since it easily
allows to push multiple versions of the same page under different urls
(and does an intelligent diff so that the upload is smaller).

Related: sagemath/documentation#24 #33263
#33294

Follow-up:
- Change the deployment url to something more official. For this reason,
I've created the site `sagemath-tobias.netlify.org`, so if you want to
create an official sage account, `sagemath.netlify.org` is still
available. Then one just needs to change the secrets in the github repo.

- Incorporate the post-fixes of
https://github.com/sagemath/documentation into the main repo here, so
that the preview looks the same as the published page.

- For pushes with tags (or to master), publish it on docs.sagemath.org
website (for example using https://github.com/marketplace/actions
/deploy-to-github-pages or by completely migrating to netlify).

URL: https://trac.sagemath.org/31415
Reported by: mkoeppe
Ticket author(s): Tobias Diez
Reviewer(s): Matthias Koeppe

.github/workflows/doc-build.yml

@@ -0,0 +1,72 @@
+name: Build documentation
+
+on:
+  push:
+  workflow_dispatch:
+    # Allow to run manually
+
+concurrency:
+  # Cancel previous runs of this workflow for the same branch
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    container: ghcr.io/sagemath/sage/sage-docker-ubuntu-focal-standard-with-targets:9.5
+    if: github.repository == 'sagemath/sagetrac-mirror'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Prepare
+        run: |
+          # Reuse built SAGE_LOCAL contained in the Docker image 
+          ./bootstrap
+          ./configure --enable-build-as-root --prefix=/sage/local --with-sage-venv
+
+      - name: Build
+        run: make doc-html
+        env:
+          MAKE: make -j2
+          SAGE_NUM_THREADS: 2
+
+      - name: Copy docs
+        run: |
+          # For some reason the deploy step below cannot find /sage/...
+          # So copy everything from there to local folder
+          # We also need to replace the symlinks because netlify is not following them
+          mkdir -p ./docs
+          cp -r -L /sage/local/share/doc/sage/html/en/* ./docs
+
+      - name: Deploy to Netlify preview
+        id: preview-netlify
+        if: github.ref != 'refs/heads/develop'
+        uses: netlify/actions/cli@master
+        with:
+          args: deploy --dir=docs --alias="${NETLIFY_ALIAS}"
+        env:
+          # Set deployment url to commit hash to easily link from the trac.
+          # We could also set NETLIFY_ALIAS to the branch name.
+          # However, netlify currently doesn't support updates to a deployment with the same alias
+          # https://github.com/netlify/cli/issues/948
+          # https://github.com/netlify/cli/issues/1984
+          # Note that even if this feature is implemented, one would also need to first process the branch name
+          # to workaround the bug https://github.com/netlify/cli/issues/969.
+          NETLIFY_ALIAS: ${{ github.sha }}
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+
+      - name: Deploy to Netlify production
+        id: deploy-netlify
+        if: github.ref == 'refs/heads/develop'
+        uses: netlify/actions/cli@master
+        with:
+          args: deploy --dir=docs --prod
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+
+      - name: Report deployment url
+        run: |
+          echo "::notice::The documentation has being automatically deployed to Netlify. %0A ✅ Preview: ${{ steps.preview-netlify.outputs.NETLIFY_URL || steps.deploy-netlify.outputs.NETLIFY_URL }}"