Use Vercel action for continuous documentation

.github/workflows/continuous-documentation.yml

@@ -83,9 +83,15 @@ jobs:
       - name: Deploy documentation to Vercel
         uses: amondnet/[email protected]
         with:
-          # https://vercel.com/account/tokens
+          # Generate a vercel token at https://vercel.com/account/tokens,
+          # and save the value in the secrets setting in the repository.
           vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          # vercel-org-id and vercel-project-id are generated using vercel CLI
+          # https://github.com/marketplace/actions/vercel-action#project-linking
+          # Install the Vercel CLI and run `vercel` in the project directory.
+          # After linking the repository with a Vercel project, `vercel` will
+          # create a `.vercel` directory containing both the organization (vercel-org-id)
+          # and project (vercel-project-id) id of the project.
+          # Save the values in the secrets setting in the repository.
           vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
           vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
           github-token: ${{ secrets.GITHUB_TOKEN }}

MAINTENANCE.md

@@ -47,7 +47,7 @@ conda and the `Makefile` to run the tests and checks.
 
 ### GitHub Actions
 
-There are 5 configuration files located in `.github/workflows`:
+There are 6 configuration files located in `.github/workflows`:
 
 1. `style_checks.yaml` (Code lint and style checks)
 
@@ -84,16 +84,19 @@ This workflow is ran to publish wheels to PyPI and TestPyPI (for testing only).
 Archives will be pushed to TestPyPI on every commit to the *master* branch and
 tagged releases, and to PyPI for tagged releases only.
 
+6. `continuous-documentation.yml` (Deploy documentation to Vercel for preview)
+
+This workflow builds and deploys the documentation in Pull Requests to Vercel,
+to make it easier to preview documentation changes.
 
 ## Continuous Documentation
 
-We use the [Vercel for GitHub](https://github.com/apps/vercel) App to preview changes
-made to our documentation website every time we make a commit in a pull request.
-The service has a configuration file `vercel.json`, with a list of options to
-change the default behaviour at https://vercel.com/docs/configuration.
-The actual script `package.json` is used by Vercel to install the necessary packages,
-build the documentation, copy the files to a 'public' folder and deploy that to the web,
-see https://vercel.com/docs/build-step.
+We use the [Vercel](https://vercel.com/) service and the
+[vercel-action](https://github.com/marketplace/actions/vercel-action) action to
+preview changes made to our documentation website every time we make a commit
+in a pull request. The workflow `continuous-documentation.yml` builds and
+deploys the documentation to Vercel and create a comment with the latest URL
+of deployment preview.
 
 ## Making a Release