Use Vercel action for continuous documentation

.github/workflows/continuous-documentation.yml

@@ -0,0 +1,99 @@
+# This workflow deploys documentation to Vercel for previewing PRs
+
+name: Continuous Documentation
+
+on:
+  pull_request:
+    paths:
+    - 'doc/**'
+    - 'examples/**'
+    - 'pygmt/**'
+    - 'README.rst'
+    - '.github/workflows/continuous-documentation.yml'
+  pull_request_target:
+    paths:
+    - 'doc/**'
+    - 'examples/**'
+    - 'pygmt/**'
+    - 'README.rst'
+    - '.github/workflows/continuous-documentation.yml'
+
+jobs:
+  vercel:
+    name: Deploy to Vercel
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/[email protected]
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Checkout
+        uses: actions/[email protected]
+        with:
+          # fecth all history so that setuptools-scm works
+          fetch-depth: 0
+
+      # Setup Miniconda
+      - name: Setup Miniconda
+        uses: conda-incubator/[email protected]
+        with:
+          activate-environment: pygmt
+          python-version: 3.9
+          channels: conda-forge
+          miniconda-version: "latest"
+
+      - name: Install dependencies
+        run: |
+          conda install gmt=6.1.1 numpy pandas xarray netcdf4 packaging \
+                        ipython myst-parser sphinx sphinx-copybutton \
+                        sphinx-gallery sphinx_rtd_theme=0.4.3
+
+      - name: List installed packages
+        run: conda list
+
+      - name: Download remote data from GitHub
+        uses: dawidd6/[email protected]
+        with:
+          workflow: cache_data.yaml
+          workflow_conclusion: success
+          name: gmt-cache
+          path: .gmt
+
+      - name: Move and list downloaded remote files
+        run: |
+          mkdir -p ~/.gmt
+          mv .gmt/* ~/.gmt
+          # Change modification times of the two files, so GMT won't refresh it
+          touch ~/.gmt/server/gmt_data_server.txt ~/.gmt/server/gmt_hash_server.txt
+          ls -lhR ~/.gmt
+
+      - name: Install the package
+        run: |
+          python setup.py sdist --formats=zip
+          pip install dist/*
+
+      - name: Build the documentation
+        run: make -C doc clean all
+
+      - name: Deploy documentation to Vercel
+        uses: amondnet/[email protected]
+        with:
+          # 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 }}
+          # 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 }}
+          github-comment: true
+          working-directory: ./doc/_build/html

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 a cloud platform service called [Vercel](https://vercel.com/) via
+[vercel-action](https://github.com/marketplace/actions/vercel-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. The vercel bot will automatically make a
+comment with a URL to preview the deployed documentation for that pull request.
 
 ## Making a Release