Merge branch 'master' into gmt-library

.github/PULL_REQUEST_TEMPLATE.md

@@ -16,6 +16,10 @@ Fixes #
 - [ ] Write detailed docstrings for all functions/methods.
 - [ ] If adding new functionality, add an example to docstrings or tutorials.
 
-**Notes**
+**Slash Commands**
 
-- You can write `/format` in the first line of a comment to lint the code automatically
+You can write slash commands (`/command`) in the first line of a comment to perform
+specific operations. Supported slash commands are:
+
+- `/format`: automatically format and lint the code
+- `/test-gmt-dev`: run full tests on the latest GMT development version

.github/workflows/ci_tests.yaml

@@ -32,10 +32,10 @@ jobs:
 
       - name: Install packages
         run: |
-          pip install black blackdoc flake8 pylint isort
+          pip install black blackdoc docformatter flake8 pylint isort
           sudo apt-get install dos2unix
 
-      - name: Formatting check (black and flake8)
+      - name: Formatting check (black, blackdoc, docformatter, flake8 and isort)
         run: make check
 
       - name: Linting (pylint)

.github/workflows/ci_tests_dev.yaml

@@ -1,13 +1,15 @@
-# This workflow installs PyGMT dependencies, builds documentation and runs tests on GMT latest
+# This workflow installs PyGMT dependencies, builds documentation and runs tests on GMT dev version
 # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
 
-name: GMT Latest Tests
+name: GMT Dev Tests
 
 on:
   # push:
   #   branches: [ master ]
   pull_request:
-    types: [review_requested, ready_for_review]
+    types: [ready_for_review]
+  repository_dispatch:
+    types: [test-gmt-dev-command]
   # Schedule daily tests
   schedule:
     - cron: '0 0 * * *'
@@ -36,10 +38,31 @@ jobs:
       # Checkout current git repository
       - name: Checkout
         uses: actions/checkout@v2.3.4
+        if: github.event_name != 'repository_dispatch'
         with:
           # fecth all history so that setuptools-scm works
           fetch-depth: 0
 
+      # Generate token from GenericMappingTools bot
+      - name: Generate token from GenericMappingTools bot
+        uses: tibdex/github-app-token@v1
+        if: github.event_name == 'repository_dispatch'
+        id: generate-token
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      # Checkout the pull request branch
+      - name: Checkout
+        uses: actions/checkout@v2
+        if: github.event_name == 'repository_dispatch'
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          repository: ${{ github.event.client_payload.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.client_payload.pull_request.head.ref }}
+          # fecth all history so that setuptools-scm works
+          fetch-depth: 0
+
       # Setup Miniconda
       - name: Setup Miniconda
         uses: conda-incubator/setup-miniconda@v2.0.0
@@ -106,3 +129,12 @@ jobs:
         with:
           name: artifact-GMT-${{ matrix.gmt_git_ref }}-${{ runner.os }}
           path: tmp-test-dir-with-unique-name
+
+      - name: Add reaction
+        uses: peter-evans/create-or-update-comment@v1
+        if: github.event_name == 'repository_dispatch'
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
+          comment-id: ${{ github.event.client_payload.github.payload.comment.id }}
+          reaction-type: hooray

.github/workflows/format-command.yml

@@ -26,7 +26,7 @@ jobs:
       # Install formatting tools
       - name: Install formatting tools
         run: |
-          pip install black blackdoc flake8 isort
+          pip install black blackdoc docformatter flake8 isort
           sudo apt-get install dos2unix
 
       # Run "make format" and commit the change to the PR branch

.github/workflows/slash-command-dispatch.yml

@@ -21,5 +21,6 @@ jobs:
           token: ${{ steps.generate-token.outputs.token }}
           commands: |
             format
+            test-gmt-dev
           issue-type: pull-request
           permission: none

.pylintrc

@@ -293,7 +293,7 @@ indent-string='    '
 max-line-length=100
 
 # Maximum number of lines in a module.
-max-module-lines=2000
+max-module-lines=3000
 
 # List of optional constructs for which whitespace checking is disabled. `dict-
 # separator` is used to allow tabulation in dicts, etc.: {1  : 1,\n222: 2}.

CONTRIBUTING.md

@@ -130,10 +130,11 @@ General guidelines for making a good gallery plot:
   dataset isn't available, open an issue requesting one and we'll work together to add
   it.
 * Add comments to explain things are aren't obvious from reading the code. Good: *Use a
-  Mercator projection and make the plot 6 inches wide*. Bad: *Draw coastlines and plot
-  the data*.
+  Mercator projection and make the plot 15 centimeters wide*. Bad: *Draw coastlines and
+  plot the data*.
 * Describe the feature that you're showcasing and link to other relevant parts of the
   documentation.
+* SI units should be used in the example code for gallery plots.
 
 ### Tutorials
 
@@ -146,6 +147,9 @@ The tutorials (the User Guide in the docs) are also built by sphinx-gallery from
 * Include the tutorial in the table of contents of the documentation (side bar). Do this
   by adding a line to the User Guide `toc` directive in `doc/index.rst`. Notice that the
   file included is the `.rst` generated by sphinx-gallery.
+* Choose the most representative figure as the thumbnail figure by adding a comment line
+  `# sphinx_gallery_thumbnail_number = <fig_number>` to any place (usually at the top)
+  in the tutorial. The *fig_number* starts from 1.
 
 Guidelines for a good tutorial:
 
@@ -155,10 +159,26 @@ Guidelines for a good tutorial:
   features or abbreviations.
 * Explain the options and features in as much detail as possible. The gallery has
   concise examples while the tutorials are detailed and full of text.
+* SI units should be used in the example code for tutorial plots.
 
 Note that the `Figure.show()` function needs to be called for a plot to be inserted into
 the documentation.
 
+### Example code standards
+
+When editing documentation, use the following standards to demonstrate the example code:
+
+1. Python arguments, such as import statements, Boolean expressions, and function
+   arguments should be wrapped as ``code`` by using \`\` on both sides of the code.
+   Example: \`\`import pygmt\`\` results in ``import pygmt``
+
+2.  Literal GMT arguments should be **bold** by wrapping the arguments with \*\*
+    (two asterisks) on both sides. The argument description should be in *italicized*
+    with \* (single asterisk) on both sides.
+    Example: `**+l**\ *label*` results in **+l***label*
+
+3. Optional arguments are placed wrapped with [ ] (square brackets).
+4. Arguments that are mutually exclusive are separated with a | (bar) to denote "or".
 
 ## Contributing Code
 
@@ -249,10 +269,11 @@ We use some tools:
 
 - [Black](https://github.com/ambv/black)
 - [blackdoc](https://github.com/keewis/blackdoc)
+- [docformatter](https://github.com/myint/docformatter)
 - [isort](https://pycqa.github.io/isort/)
 
 to format the code so we don't have to think about it.
-Black loosely follows the [PEP8](http://pep8.org) guide but with a few differences.
+Black and blackdoc loosely follows the [PEP8](http://pep8.org) guide but with a few differences.
 Regardless, you won't have to worry about formatting the code yourself.
 Before committing, run it to automatically format your code:
 
@@ -273,7 +294,7 @@ common errors.
 The [`Makefile`](Makefile) contains rules for running both checks:
 
 ```bash
-make check   # Runs flake8, black, blackdoc and isort (in check mode)
+make check   # Runs black, blackdoc, docformatter, flake8 and isort (in check mode)
 make lint    # Runs pylint, which is a bit slower
 ```
 
@@ -300,6 +321,12 @@ Please write tests for your code so that we can be sure that it won't break any
 existing functionality.
 Tests also help us be confident that we won't break your code in the future.
 
+When writing tests, don't test everything that the GMT function already tests, such as
+the every unique combination arguments. An exception to this would be the most popular
+modules, such as `plot` and `basemap`. The highest priority for tests should be the
+Python-specific code, such as numpy, pandas, and xarray objects and the virtualfile
+mechanism.
+
 If you're **new to testing**, see existing test files for examples of things to do.
 **Don't let the tests keep you from submitting your contribution!**
 If you're not sure how to do this or are having trouble, submit your pull request

MAINTENANCE.md

@@ -60,10 +60,10 @@ On the *master* branch, the workflow also handles the documentation deployment:
   *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/Windows).
+2. `ci_tests_dev.yaml` (GMT Dev Tests on Linux/macOS/Windows).
 
-This is only triggered when a review is requested or re-requested on a PR.
-It is also scheduled to run daily on the *master* branch.
+This is triggered when a PR is marked as "ready for review", or using the slash
+command `/test-gmt-dev`. It is also scheduled to run daily on the *master* branch.
 
 3. `cache_data.yaml` (Caches GMT remote data files needed for GitHub Actions CI)
 

Makefile

@@ -6,6 +6,8 @@ PYTEST_COV_ARGS=--cov=$(PROJECT) --cov-config=../pyproject.toml \
 			--pyargs ${PYTEST_EXTRA}
 BLACK_FILES=$(PROJECT) setup.py doc/conf.py examples
 BLACKDOC_OPTIONS=--line-length 79
+DOCFORMATTER_FILES=$(PROJECT) setup.py doc/conf.py examples
+DOCFORMATTER_OPTIONS=--recursive --pre-summary-newline --make-summary-multi-line --wrap-summaries 79 --wrap-descriptions 79
 FLAKE8_FILES=$(PROJECT) setup.py doc/conf.py
 LINT_FILES=$(PROJECT) setup.py doc/conf.py
 
@@ -14,8 +16,8 @@ help:
 	@echo ""
 	@echo "  install   install in editable mode"
 	@echo "  test      run the test suite (including doctests) and report coverage"
-	@echo "  format    run black and blackdoc to automatically format the code"
-	@echo "  check     run code style and quality checks (black, blackdoc, isort and flake8)"
+	@echo "  format    run black, blackdoc, docformatter and isort to automatically format the code"
+	@echo "  check     run code style and quality checks (black, blackdoc, docformatter, flake8 and isort)"
 	@echo "  lint      run pylint for a deeper (and slower) quality check"
 	@echo "  clean     clean up build and generated files"
 	@echo "  distclean clean up build and generated files, including project metadata files"
@@ -37,11 +39,13 @@ test:
 
 format:
 	isort .
+	docformatter --in-place $(DOCFORMATTER_OPTIONS) $(DOCFORMATTER_FILES)
 	black $(BLACK_FILES)
 	blackdoc $(BLACKDOC_OPTIONS) $(BLACK_FILES)
 
 check:
 	isort . --check
+	docformatter --check $(DOCFORMATTER_OPTIONS) $(DOCFORMATTER_FILES)
 	black --check $(BLACK_FILES)
 	blackdoc --check $(BLACKDOC_OPTIONS) $(BLACK_FILES)
 	flake8 $(FLAKE8_FILES)
@@ -59,4 +63,4 @@ clean:
 	rm -rvf result_images
 
 distclean: clean
-	rm -r *.egg-info
+	rm -rvf *.egg-info

README.rst

@@ -13,8 +13,8 @@ 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
-.. image:: https://github.com/GenericMappingTools/pygmt/workflows/GMT%20Latest%20Tests/badge.svg
-    :alt: GitHub Actions GMT Latest Tests status
+.. image:: https://github.com/GenericMappingTools/pygmt/workflows/GMT%20Dev%20Tests/badge.svg
+    :alt: GitHub Actions GMT Dev Tests status
     :target: https://github.com/GenericMappingTools/pygmt/actions?query=workflow%3A%22GMT+Latest+Tests%22
 .. image:: https://img.shields.io/codecov/c/github/GenericMappingTools/pygmt/master.svg?style=flat-square
     :alt: Test coverage status

doc/conf.py

@@ -89,6 +89,8 @@
     # Insert links to documentation of objects in the examples
     "reference_url": {"pygmt": None},
     "image_scrapers": (PyGMTScraper(),),
+    # Removes configuration comments from scripts
+    "remove_config_comments": True,
 }
 
 # Sphinx project configuration

doc/index.rst

@@ -31,8 +31,9 @@
     tutorials/frames.rst
     projections/index.rst
     tutorials/coastlines.rst
+    tutorials/regions.rst
     tutorials/plot.rst
-    tutorials/plot-lines.rst
+    tutorials/lines.rst
     tutorials/text.rst
     tutorials/contour-map.rst
     tutorials/earth-relief.rst

environment.yml

@@ -11,19 +11,20 @@ dependencies:
     - xarray
     - netCDF4
     - packaging
-    - ipython
-    - matplotlib
-    - jupyter
-    - pytest>=6.0
-    - pytest-cov
-    - pytest-mpl
-    - coverage[toml]
     - black
     - blackdoc
+    - coverage[toml]
+    - docformatter
+    - flake8
+    - ipython
     - isort>=5
+    - jupyter
+    - matplotlib
+    - nbsphinx
     - pylint
-    - flake8
+    - pytest-cov
+    - pytest-mpl
+    - pytest>=6.0
     - sphinx
-    - sphinx_rtd_theme=0.4.3
     - sphinx-gallery
-    - nbsphinx
+    - sphinx_rtd_theme=0.4.3

examples/gallery/coast/borders.py

@@ -18,8 +18,8 @@
 import pygmt
 
 fig = pygmt.Figure()
-# Make a Sinusoidal projection map of the Americas with automatic ticks
-fig.basemap(region=[-150, -30, -60, 60], projection="I-90/8i", frame="afg")
+# Make a Sinusoidal projection map of the Americas with automatic annotations, ticks and gridlines
+fig.basemap(region=[-150, -30, -60, 60], projection="I-90/15c", frame="afg")
 # Plot each level of the boundaries dataset with a different color.
 fig.coast(borders=["1/0.5p,black", "2/0.5p,red", "3/0.5p,blue"], land="gray")
 fig.show()

examples/gallery/coast/land_and_water.py

@@ -10,7 +10,7 @@
 
 fig = pygmt.Figure()
 # Make a global Mollweide map with automatic ticks
-fig.basemap(region="g", projection="W8i", frame=True)
-# Plot the land as light gray
+fig.basemap(region="g", projection="W15c", frame=True)
+# Plot the land as light gray, and the water as sky blue
 fig.coast(land="#666666", water="skyblue")
 fig.show()

examples/gallery/coast/shorelines.py

@@ -8,7 +8,7 @@
 
 fig = pygmt.Figure()
 # Make a global Mollweide map with automatic ticks
-fig.basemap(region="g", projection="W8i", frame=True)
+fig.basemap(region="g", projection="W15c", frame=True)
 # Display the shorelines as black lines with 0.5 point thickness
 fig.coast(shorelines="0.5p,black")
 fig.show()

examples/gallery/grid/grdview_surface.py

@@ -37,12 +37,12 @@ def ackley(x, y):
 fig = pygmt.Figure()
 
 # Plot grid as a 3-D surface
-SCALE = 0.2  # [inches]
+SCALE = 0.5  # in centimeter
 fig.grdview(
     data,
     frame=["a5f1", "za5f1"],
-    projection=f"x{SCALE}i",
-    zscale=f"{SCALE}i",
+    projection=f"x{SCALE}c",
+    zscale=f"{SCALE}c",
     surftype="s",
     cmap="roma",
     perspective=[135, 30],  # Azimuth southeast (135°), at elevation 30°

examples/gallery/grid/track_sampling.py

@@ -4,13 +4,13 @@
 
 The :func:`pygmt.grdtrack` function samples a raster grid's value along specified
 points. We will need to input a 2D raster to ``grid`` which can be an
-``xarray.DataArray``. The ``points`` parameter can be a ``pandas.DataFrame`` table where
+:class:`xarray.DataArray`. The ``points`` argument can be a :class:`pandas.DataFrame` table where
 the first two columns are x and y (or longitude and latitude). Note also that there is a
-``newcolname`` parameter that will be used to name the new column of values we sampled
+``newcolname`` argument that will be used to name the new column of values we sampled
 from the grid.
 
 Alternatively, we can provide a NetCDF file path to ``grid``. An ASCII file path can
-also be accepted for ``points``, but an ``outfile`` parameter will then need to be set
+also be accepted for ``points``, but an ``outfile`` argument will then need to be set
 to name the resulting output ASCII file.
 """
 
@@ -24,10 +24,10 @@
 
 fig = pygmt.Figure()
 # Plot the earth relief grid on Cylindrical Stereographic projection, masking land areas
-fig.basemap(region="g", frame=True, projection="Cyl_stere/150/-20/8i")
+fig.basemap(region="g", frame=True, projection="Cyl_stere/150/-20/15c")
 fig.grdimage(grid=grid, cmap="gray")
 fig.coast(land="#666666")
-# Plot using circles (c) of 0.15cm, the sampled bathymetry points
+# Plot using circles (c) of 0.15 cm, the sampled bathymetry points
 # Points are colored using elevation values (normalized for visual purposes)
 fig.plot(
     x=track.longitude,