Merge branch 'master' into docstring-formatter

Author: seisman

.github/workflows/ci_tests.yaml

@@ -7,6 +7,9 @@ on:
   push:
     branches: [ master ]
   pull_request:
+  release:
+    types:
+      - published
   # Schedule daily tests
   schedule:
     - cron: '0 0 * * *'
@@ -138,3 +141,64 @@ jobs:
           file: ./coverage.xml # optional
           env_vars: OS,PYTHON
           fail_ci_if_error: true
+
+      - name: Checkout the gh-pages branch
+        uses: actions/checkout@28c7f3d2b5162b5ddd3dfd9a45aa55eaf396478b
+        with:
+          ref: gh-pages
+          # Checkout to this folder instead of the current one
+          path: deploy
+          # Download the entire history
+          fetch-depth: 0
+        if: (github.event_name == 'release' || github.event_name == 'push') && (matrix.os == 'ubuntu-latest') && (matrix.python-version == '3.9')
+
+      - name: Push the built HTML to gh-pages
+        run: |
+          # Detect if this is a release or from the master branch
+          if [[ "${GITHUB_EVENT_NAME}" == "release" ]]; then
+              # Get the tag name without the "refs/tags/" part
+              version="${GITHUB_REF#refs/*/}"
+          else
+              version=dev
+          fi
+          echo "Deploying version: $version"
+          # Make the new commit message. Needs to happen before cd into deploy
+          # to get the right commit hash.
+          message="Deploy $version from $(git rev-parse --short HEAD)"
+          cd deploy
+          # Need to have this file so that Github doesn't try to run Jekyll
+          touch .nojekyll
+          # Delete all the files and replace with our new  set
+          echo -e "\nRemoving old files from previous builds of ${version}:"
+          rm -rvf ${version}
+          echo -e "\nCopying HTML files to ${version}:"
+          cp -Rvf ../doc/_build/html/ ${version}/
+          # If this is a new release, update the link from /latest to it
+          if [[ "${version}" != "dev" ]]; then
+              echo -e "\nSetup link from ${version} to 'latest'."
+              rm -f latest
+              ln -sf ${version} latest
+          fi
+          # Stage the commit
+          git add -A .
+          echo -e "\nChanges to be applied:"
+          git status
+          # Configure git to be the GitHub Actions account
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+          # If this is a dev build and the last commit was from a dev build
+          # (detect if "dev" was in the previous commit message), reuse the
+          # same commit
+          if [[ "${version}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then
+              echo -e "\nAmending last commit:"
+              git commit --amend --reset-author -m "$message"
+          else
+              echo -e "\nMaking a new commit:"
+              git commit -m "$message"
+          fi
+          # Make the push quiet just in case there is anything that could leak
+          # sensitive information.
+          echo -e "\nPushing changes to gh-pages."
+          git push -fq origin gh-pages 2>&1 >/dev/null
+          echo -e "\nFinished uploading generated files."
+        if: (github.event_name == 'release' || github.event_name == 'push') && (matrix.os == 'ubuntu-latest') && (matrix.python-version == '3.9')

.travis.yml

@@ -10,6 +10,7 @@ and are considered the "PyGMT Developers":
 
 * [Wei Ji Leong](https://github.com/weiji14)
 * [Tyler Newton](http://www.tnewton.com/)
+* [William Schlitzer](https://github.com/willschlitzer)
 * [Dongdong Tian](https://seisman.info/)
 * [Liam Toney](https://liam.earth/)
 * [Leonardo Uieda](http://www.leouieda.com/)

AUTHORS.md

@@ -312,11 +312,11 @@ Leave a comment in the PR and we'll help you out.
 
 You can also run tests in just one test script using:
 
-    pytest --verbose --mpl --mpl-results-path=results --doctest-modules pygmt/tests/NAME_OF_TEST_FILE.py
+    pytest pygmt/tests/NAME_OF_TEST_FILE.py
 
 or run tests which contain names that match a specific keyword expression:
 
-    pytest --verbose --mpl --mpl-results-path=results --doctest-modules -k KEYWORD pygmt/tests
+    pytest -k KEYWORD pygmt/tests
 
 ### Testing plots
 
@@ -436,7 +436,7 @@ Some things that will increase the chance that your pull request is accepted qui
   [numpy guide](https://numpydoc.readthedocs.io/en/latest/format.html)
   for documentation.
 
-Pull requests will automatically have tests run by TravisCI.
+Pull requests will automatically have tests run by GitHub Actions.
 This includes running both the unit tests as well as code linters.
 GitHub will show the status of these checks on the pull request.
 Try to get them all passing (green).

CONTRIBUTING.md

@@ -13,7 +13,7 @@ If you want to make a contribution to the project, see the
   branch. Make a new branch and submit a pull request instead.
 * *gh-pages*: Holds the HTML documentation and is served by GitHub. Pages for the master
   branch are in the `dev` folder. Pages for each release are in their own folders.
-  **Automatically updated by TravisCI** so you shouldn't have to make commits here.
+  **Automatically updated by GitHub Actions** so you shouldn't have to make commits here.
 
 
 ## Reviewing and merging pull requests
@@ -40,7 +40,7 @@ The main advantages of this are:
 
 ## Continuous Integration
 
-We use GitHub Actions and TravisCI continuous integration (CI) services to
+We use GitHub Actions continuous integration (CI) services to
 build and test the project on Linux, macOS and Windows.
 They rely on the `requirements.txt` file to install required dependencies using
 conda and the `Makefile` to run the tests and checks.
@@ -54,6 +54,12 @@ There are 4 configuration files located in `.github/workflows`:
 This is ran on every commit on the *master* and Pull Request branches.
 It is also scheduled to run daily on the *master* branch.
 
+On the *master* branch, the workflow also handles the documentation deployment:
+
+* Updating the development documentation by pushing the built HTML pages from the
+  *master* branch onto the `dev` folder of the *gh-pages* branch.
+* Updated the `latest` documentation link to the new release.
+
 2. `ci_tests_dev.yaml` (GMT Latest Tests on Linux/macOS).
 
 This is only triggered when a review is requested or re-requested on a PR.
@@ -72,23 +78,6 @@ Archives will be pushed to TestPyPI on every commit to the *master* branch and
 tagged releases, and to PyPI for tagged releases only.
 
 
-### Travis CI
-
-The configuration file is at `.travis.yml`.
-Travis runs tests (Linux only) and handles the documentation deployment automatically:
-
-* Updating the development documentation by pushing the built HTML pages from the
-  *master* branch onto the `dev` folder of the *gh-pages* branch.
-* Updated the `latest` documentation link to the new release.
-
-This way, most day-to-day maintenance operations are automatic.
-
-The scripts that setup the test environment and run the deployments are loaded from the
-[fatiando/continuous-integration](https://github.com/fatiando/continuous-integration)
-repository to avoid duplicating work across multiple repositories.
-If you find any problems with the test setup and deployment, please create issues and
-submit pull requests to that repository.
-
 ## Continuous Documentation
 
 We use the [Zeit Now for GitHub integration](https://zeit.co/github) to preview changes
@@ -102,7 +91,7 @@ see https://zeit.co/docs/v2/build-step/?query=package.json#defining-a-build-scri
 ## Making a Release
 
 We try to automate the release process as much as possible.
-Travis handles publishing new releases to PyPI and updating the documentation.
+GitHub Actions workflow handles publishing new releases to PyPI and updating the documentation.
 The version number is set automatically using setuptools_scm based information
 obtained from git.
 There are a few steps that still must be done manually, though.
@@ -166,7 +155,7 @@ and clicking on publish. A git tag will also be created, make sure that this
 tag is a proper version number (following [Semantic Versioning](https://semver.org/))
 with a leading `v`. E.g. `v0.2.1`.
 
-Once the release/tag is created, this should trigger Travis to do all the work for us.
+Once the release/tag is created, this should trigger GitHub Actions to do all the work for us.
 A new source distribution will be uploaded to PyPI, a new folder with the documentation
 HTML will be pushed to *gh-pages*, and the `latest` link will be updated to point to
 this new folder.

MAINTENANCE.md

@@ -1,9 +1,8 @@
 # Build, package, test, and clean
 PROJECT=pygmt
 TESTDIR=tmp-test-dir-with-unique-name
-PYTEST_ARGS=--cov=$(PROJECT) --cov-config=../pyproject.toml \
+PYTEST_COV_ARGS=--cov=$(PROJECT) --cov-config=../pyproject.toml \
 			--cov-report=term-missing --cov-report=xml --cov-report=html \
-			--doctest-modules -v --mpl --mpl-results-path=results \
 			--pyargs ${PYTEST_EXTRA}
 BLACK_FILES=$(PROJECT) setup.py doc/conf.py examples
 BLACKDOC_OPTIONS=--line-length 79
@@ -32,7 +31,7 @@ test:
 	@echo ""
 	@cd $(TESTDIR); python -c "import $(PROJECT); $(PROJECT).show_versions()"
 	@echo ""
-	cd $(TESTDIR); pytest $(PYTEST_ARGS) $(PROJECT)
+	cd $(TESTDIR); pytest $(PYTEST_COV_ARGS) $(PROJECT)
 	cp $(TESTDIR)/coverage.xml .
 	cp -r $(TESTDIR)/htmlcov .
 	rm -r $(TESTDIR)

Makefile

@@ -10,9 +10,6 @@ PyGMT
 .. image:: http://img.shields.io/pypi/v/pygmt.svg?style=flat-square
     :alt: Latest version on PyPI
     :target: https://pypi.python.org/pypi/pygmt
-.. image:: http://img.shields.io/travis/GenericMappingTools/pygmt/master.svg?style=flat-square&label=Linux
-    :alt: Travis CI build status
-    :target: https://travis-ci.org/GenericMappingTools/pygmt
 .. image:: https://github.com/GenericMappingTools/pygmt/workflows/Tests/badge.svg
     :alt: GitHub Actions Tests status
     :target: https://github.com/GenericMappingTools/pygmt/actions?query=workflow%3ATests

README.rst

@@ -33,6 +33,8 @@
     tutorials/coastlines.rst
     tutorials/plot.rst
     tutorials/text.rst
+    tutorials/contour-map.rst
+    tutorials/earth-relief.rst
     tutorials/configuration.rst
 
 .. toctree::

doc/index.rst

@@ -14,7 +14,7 @@ dependencies:
     - ipython
     - matplotlib
     - jupyter
-    - pytest
+    - pytest>=6.0
     - pytest-cov
     - pytest-mpl
     - coverage[toml]
@@ -23,7 +23,7 @@ dependencies:
     - docformatter
     - pylint
     - flake8
-    - sphinx=2.2.1
+    - sphinx
     - sphinx_rtd_theme=0.4.3
     - sphinx-gallery
     - nbsphinx

environment.yml

@@ -4,7 +4,7 @@
 
 The :meth:`pygmt.Figure.plot3d` method can be used to plot symbols in 3D.
 In the example below, we show how the
-`Iris flower dataset <https://en.wikipedia.org/wiki/Iris_flower_data_set/>`__
+`Iris flower dataset <https://en.wikipedia.org/wiki/Iris_flower_data_set>`__
 can be visualized using a perspective 3-dimensional plot. The ``region``
 argument has to include the :math:`x`, :math:`y`, :math:`z` axis limits in the
 form of (xmin, xmax, ymin, ymax, zmin, zmax), which can be done automatically