Migrate Continuous Documentation from Vercel to Readthedocs (GenericMappingTools#1859)

* Remove vercel configuration files
* Setup readthedocs configuration file
* Run pip install . in the readthedocs build environment
* Remove vercel configurations and add readthedocs configurations in MANIFEST.in
* Update doc/maintenance.md to trigger builds in PR
* Set canonical URL by setting html_baseurl
* Update contributing and maintenance guides
* Customize the pre_build step to generate API stub files
* Only install packages required for building docs
* Move the docs environment file to the ci directory

Co-authored-by: Dongdong Tian <[email protected]>

Author: 2 people

.readthedocs.yaml

@@ -0,0 +1,30 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "mambaforge-4.10"
+  jobs:
+    pre_build: # Generate api stub files before building
+      - make -C doc api
+
+# Build documentation in the doc/ directory with Sphinx
+sphinx:
+   configuration: doc/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+conda:
+  environment: ci/requirements/docs.yml
+python:
+   install:
+   - method: pip
+     path: .

MANIFEST.in

@@ -1,13 +1,13 @@
 prune .dvc
 prune .github*
+prune ci
 prune doc*
 prune examples*
 exclude .dvcignore
 exclude .gitignore
+exclude .readthedocs.yaml
 exclude AUTHORSHIP.md
 exclude CONTRIBUTING.md
 exclude Makefile
 exclude environment.yml
-exclude package.json
 exclude requirements.txt
-exclude vercel.json

ci/requirements/docs.yml

@@ -0,0 +1,26 @@
+name: pygmt
+channels:
+    - conda-forge
+    - defaults
+dependencies:
+    # Required dependencies
+    - pip
+    - gmt=6.3.0
+    - numpy>=1.20
+    - pandas
+    - xarray
+    - netCDF4
+    - packaging
+    # Optional dependencies
+    - geopandas
+    # Development dependencies (general)
+    - build
+    - ipython
+    - make
+    # Dev dependencies (building documentation)
+    - myst-parser
+    - sphinx
+    - sphinx-copybutton
+    - sphinx-design
+    - sphinx-gallery
+    - sphinx_rtd_theme

doc/conf.py

@@ -142,6 +142,7 @@
 .. |year| replace:: {year}
 """
 
+html_baseurl = "https://pygmt.org/latest/"
 html_last_updated_fmt = "%b %d, %Y"
 html_title = "PyGMT"
 html_short_title = "PyGMT"

doc/contributing.md

@@ -289,8 +289,8 @@ download and install anything:
   click on the "Propose changes" button to open a pull request.
 7. The pull request will run the GMT automated tests and make a preview deployment.
   You can see how your change looks in the PyGMT documentation by clicking the
-  "View deployment" button after the Vercel bot has finished (usually 5-10 minutes
-  after the pull request was created).
+  "Details" button of the "docs/readthedocs.org:pygmt-dev" status check,
+  after the building has finished (usually 10-15 minutes after the pull request was created).
 8. We'll review your pull request, recommend changes if necessary, and then merge
   them in if everything is OK.
 9. Done!

doc/maintenance.md

@@ -151,13 +151,10 @@ There are 11 configuration files located in `.github/workflows`:
 
 ## Continuous Documentation
 
-We use the [Vercel for GitHub](https://github.com/apps/vercel) App to preview changes
+We use the [ReadtheDocs](https://readthedocs.org/) service 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.
+The service has a configuration file `.readthedocs.yaml`, with a list of options
+to change the default behaviour at https://docs.readthedocs.io/en/stable/config-file/index.html.
 
 
 ## Dependencies Policy