Merge branch 'main' into ci/python-3.10

Author: weiji14

.github/workflows/check-links.yml

@@ -26,7 +26,7 @@ jobs:
         path: documentation
 
     - name: Link Checker
-      uses: lycheeverse/lychee-action@v1.0.9
+      uses: lycheeverse/lychee-action@v1.1.1
       with:
         # 429: Too many requests
         args: >

.github/workflows/ci_docs.yml

@@ -80,7 +80,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.15.0
+        uses: dawidd6/action-download-artifact@v2.16.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

.github/workflows/ci_tests.yaml

@@ -105,7 +105,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.15.0
+        uses: dawidd6/action-download-artifact@v2.16.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

.github/workflows/ci_tests_dev.yaml

@@ -109,7 +109,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.15.0
+        uses: dawidd6/action-download-artifact@v2.16.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

.github/workflows/format-command.yml

@@ -21,7 +21,7 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha }}
 
       # Setup Python environment
-      - uses: actions/setup-python@v2.2.2
+      - uses: actions/setup-python@v2.3.1
 
       # Install formatting tools
       - name: Install formatting tools

.github/workflows/publish-to-pypi.yml

@@ -29,7 +29,7 @@ jobs:
         fetch-depth: 0
 
     - name: Set up Python
-      uses: actions/setup-python@v2.2.2
+      uses: actions/setup-python@v2.3.1
       with:
         python-version: '3.10'
 

.github/workflows/release-baseline-images.yml

@@ -34,7 +34,7 @@ jobs:
         shasum -a 256 baseline-images.zip
 
     - name: Upload baseline image as a release asset
-      uses: shogo82148/actions-upload-release-asset@v1.3.2
+      uses: shogo82148/actions-upload-release-asset@v1.4.0
       with:
         upload_url: ${{ github.event.release.upload_url }}
         asset_path: baseline-images.zip

.github/workflows/style_checks.yaml

@@ -20,7 +20,7 @@ jobs:
 
       # Setup Miniconda
       - name: Set up Python
-        uses: actions/setup-python@v2.2.2
+        uses: actions/setup-python@v2.3.1
         with:
           python-version: '3.10'
 

AUTHORS.md

@@ -9,7 +9,7 @@ The following people have contributed code and/or documentation to the project
 (alphabetical by name) and are considered to be "PyGMT Developers":
 
 * [Abhishek Anant](https://twitter.com/itsabhianant) | [0000-0002-5751-2010](https://orcid.org/0000-0002-5751-2010) | Unaffiliated
-* [Dongdong Tian](https://seisman.info/) | [0000-0001-7967-1197](https://orcid.org/0000-0001-7967-1197) | Michigan State University
+* [Dongdong Tian](https://seisman.info/) | [0000-0001-7967-1197](https://orcid.org/0000-0001-7967-1197) | China University of Geosciences
 * [Jamie Quinn](http://jamiejquinn.com) | [0000-0002-0268-7032](https://orcid.org/0000-0002-0268-7032) | University College London
 * [Jiayuan Yao](https://github.com/core-man) | [0000-0001-7036-4238](https://orcid.org/0000-0001-7036-4238) | Nanyang Technological University
 * [Kathryn Materna](https://github.com/kmaterna) | [0000-0002-6687-980X](https://orcid.org/0000-0002-6687-980X) | US Geological Survey

CITATION.cff

@@ -10,7 +10,7 @@ authors:
   orcid: https://orcid.org/0000-0001-6123-9515
 - given-names: Dongdong
   family-names: Tian
-  affiliation: Michigan State University, USA
+  affiliation: China University of Geosciences, China
   orcid: https://orcid.org/0000-0001-7967-1197
 - given-names: Wei Ji
   family-names: Leong

doc/Makefile

@@ -13,11 +13,12 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees  $(SPHINXOPTS) .
 
 help:
 	@echo "Please use 'make <target>' where <target> is one of"
-	@echo "  all        build the HTML files from the existing rst sources"
-	@echo "  api        generate rst source files of API documentation"
-	@echo "  html       build the HTML files from the existing rst sources"
-	@echo "  server     make a local HTTP server for previewing the built documentation"
-	@echo "  clean      clean up built and generated files"
+	@echo "  all          build the HTML files from the existing rst sources"
+	@echo "  api          generate rst source files of API documentation"
+	@echo "  html         build the HTML files from the existing rst sources"
+	@echo "  html-noplot  build the HTML files without running any examples"
+	@echo "  server       make a local HTTP server for previewing the built documentation"
+	@echo "  clean        clean up built and generated files"
 
 all: html
 
@@ -36,6 +37,14 @@ html: api
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+html-noplot: api
+	@echo
+	@echo "Building HTML files without example plots."
+	@echo
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 server:
 	@echo
 	@echo "Running a server on port 8009."

doc/conf.py

@@ -87,6 +87,8 @@
             "../examples/projections/misc",
             "../examples/projections/nongeo",
             "../examples/projections/table",
+            "../examples/tutorials/basics",
+            "../examples/tutorials/advanced",
         ]
     ),
     # Patter to search for example files

doc/contributing.md

@@ -50,6 +50,27 @@ top of the GitHub repository and click *New Issue*.
 * After submitting your bug report, try to answer any follow up questions about the bug
   as best as you can.
 
+#### Reporting upstream bugs
+
+If you are aware that a bug is caused by an upstream GMT issue rather than a
+PyGMT-specific issue, you can optionally take the following steps to help resolve
+the problem:
+
+* Add the line `pygmt.config(GMT_VERBOSE='d')` after your import statements, which
+  will report the equivalent GMT commands as one of the debug messages.
+* Either append all messages from running your script to your GitHub issue, or
+  filter the messages to include only the GMT-equivalent commands using a command
+  such as:
+
+      python <test>.py 2>&1 | awk -F': ' '$2=="GMT_Call_Command string" {print "gmt", $3}'
+
+  where `<test>` is the name of your test script.
+* If the bug is produced when passing an in-memory data object (e.g., a
+  pandas.DataFrame or xarray.DataArray) to a PyGMT function, try writing the
+  data to a file (e.g., a NetCDF or ASCII txt file) and passing the data file
+  to the PyGMT function instead. In the GitHub issue, please share the results
+  for both cases along with your code.
+
 ### Submitting a Feature Request
 
 * Find the [*Issues*](https://github.com/GenericMappingTools/pygmt/issues) tab on the
@@ -223,7 +244,7 @@ There are four main components to PyGMT's documentation:
 The documentation are written primarily in
 [reStructuredText](https://docutils.sourceforge.io/rst.html) and built by
 [Sphinx](http://www.sphinx-doc.org/). Please refer to
-[reStructuredText Cheatsheet](https://docs.generic-mapping-tools.org/latest/rst-cheatsheet.html)
+[reStructuredText Cheatsheet](https://docs.generic-mapping-tools.org/latest/devdocs/rst-cheatsheet.html)
 if you are new to reStructuredText. When contributing documentation, be sure to
 follow the general guidelines in the [pull request workflow](#pull-request-workflow)
 section.
@@ -322,12 +343,9 @@ General guidelines for making a good gallery plot:
 The tutorials (the User Guide in the docs) are also built by sphinx-gallery from the
 `.py` files in the `examples/tutorials` folder of the repository. To add a new tutorial:
 
-* Include a `.py` file in the `examples/tutorials` folder on the base of the repository.
+* Create a `.py` file in the `examples/tutorials/advanced` folder.
 * Write the tutorial in "notebook" style with code mixed with paragraphs explaining what
   is being done. See the other tutorials for the format.
-* 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.

doc/index.rst

@@ -20,36 +20,17 @@
 
     overview.rst
     install.rst
-    tutorials/first_figure.rst
-
-.. toctree::
-    :maxdepth: 2
-    :hidden:
-    :caption: Examples
-
-    gallery/index.rst
-    external_resources.md
+    tutorials/basics/first_figure.rst
 
 .. toctree::
     :maxdepth: 2
     :hidden:
     :caption: User Guide
 
-    tutorials/frames.rst
+    tutorials/index.rst
+    gallery/index.rst
     projections/index.rst
-    tutorials/coastlines.rst
-    tutorials/regions.rst
-    tutorials/plot.rst
-    tutorials/lines.rst
-    tutorials/vectors.rst
-    tutorials/date_time_charts.rst
-    tutorials/text.rst
-    tutorials/contour_map.rst
-    tutorials/earth_relief.rst
-    tutorials/3d_perspective_image.rst
-    tutorials/insets.rst
-    tutorials/subplots.rst
-    tutorials/configuration.rst
+    external_resources.md
 
 .. toctree::
     :maxdepth: 2

doc/install.rst

@@ -3,17 +3,6 @@
 Installing
 ==========
 
-.. note::
-
-   🚨 **This package is in the early stages of design and implementation.** 🚨
-
-    We welcome any feedback and ideas!
-    Let us know by submitting
-    `issues on GitHub <https://github.com/GenericMappingTools/pygmt/issues>`__
-    or by posting on our `Discourse forum
-    <https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a>`__.
-
-
 Quickstart
 ----------
 

doc/overview.rst

@@ -29,6 +29,12 @@ The development of PyGMT has been supported by NSF grants
 `OCE-1558403 <https://www.nsf.gov/awardsearch/showAward?AWD_ID=1558403>`__ and
 `EAR-1948603 <https://www.nsf.gov/awardsearch/showAward?AWD_ID=1948602>`__.
 
+We welcome any feedback and ideas! Let us know by submitting
+`issues on GitHub <https://github.com/GenericMappingTools/pygmt/issues>`__
+or by posting on our `Discourse forum
+<https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a>`__.
+
+
 Presentations
 -------------
 

examples/gallery/histograms/blockm.py

@@ -0,0 +1,63 @@
+"""
+Blockmean
+---------
+The :meth:`pygmt.blockmean` method calculates different quantities
+inside blocks/bins whose dimensions are defined via the ``spacing`` parameter.
+The following examples show how to calculate the averages of the given values
+inside each bin and how to report the number of points inside each bin.
+"""
+
+import pygmt
+
+# Load sample data
+data = pygmt.datasets.load_japan_quakes()
+# Select only needed columns
+data = data[["longitude", "latitude", "depth_km"]]
+
+# Set the region for the plot
+region = [130, 152.5, 32.5, 52.5]
+# Define spacing in x and y direction (150 by 150 minute blocks)
+spacing = "150m"
+
+fig = pygmt.Figure()
+
+# Calculate mean depth in km from all events within 150x150 minute
+# bins using blockmean
+df = pygmt.blockmean(data=data, region=region, spacing=spacing)
+# convert to grid
+grd = pygmt.xyz2grd(data=df, region=region, spacing=spacing)
+
+fig.grdimage(
+    grid=grd,
+    region=region,
+    frame=["af", '+t"Mean earthquake depth inside each block"'],
+    cmap="batlow",
+)
+# plot slightly transparent landmasses on top
+fig.coast(land="darkgray", transparency=40)
+# plot original data points
+fig.plot(
+    x=data.longitude, y=data.latitude, style="c0.3c", color="white", pen="1p,black"
+)
+fig.colorbar(frame=["x+lkm"])
+
+fig.shift_origin(xshift="w+5c")
+
+# Calculate number of total locations within 150x150 minute bins via
+# blockmean's summary parameter
+df = pygmt.blockmean(data=data, region=region, spacing=spacing, summary="n")
+grd = pygmt.xyz2grd(data=df, region=region, spacing=spacing)
+
+fig.grdimage(
+    grid=grd,
+    region=region,
+    frame=["af", '+t"Number of points inside each block"'],
+    cmap="batlow",
+)
+fig.coast(land="darkgray", transparency=40)
+fig.plot(
+    x=data.longitude, y=data.latitude, style="c0.3c", color="white", pen="1p,black"
+)
+fig.colorbar(frame=["x+lcount"])
+
+fig.show()

examples/tutorials/README.txt

@@ -1,2 +1,6 @@
+.. _tutorials:
+
 Tutorials
 =========
+
+These examples teach us how to complete various tasks using PyGMT!

examples/tutorials/3d_perspective_image.py renamed to examples/tutorials/advanced/3d_perspective_image.py

@@ -0,0 +1,2 @@
+Advanced
+--------

examples/tutorials/advanced/README.txt

@@ -11,7 +11,7 @@
 The following examples will demonstrate how to create plots
 using the different datetime objects.
 """
-# sphinx_gallery_thumbnail_number = 0
+# sphinx_gallery_thumbnail_number = 8
 
 import datetime
 
@@ -285,7 +285,7 @@
 # Starting off with ``WS``, adding this string means that only
 # Western/Left (**W**) and Southern/Bottom (**S**) borders of
 # the plot will be shown. For more information on this, please
-# refer to :doc:`frame instructions </tutorials/frames>`.
+# refer to :doc:`frame instructions </tutorials/basics/frames>`.
 #
 # The other important item in the ``frame`` list is
 # ``"sxa1Of1D"``. This string modifies the secondary

examples/tutorials/configuration.py renamed to examples/tutorials/advanced/configuration.py

@@ -0,0 +1,2 @@
+Basics
+------

examples/tutorials/contour_map.py renamed to examples/tutorials/advanced/contour_map.py

@@ -264,7 +264,7 @@ def savefig(
         if show:
             launch_external_viewer(fname)
 
-    def show(self, dpi=300, width=500, method=None):
+    def show(self, dpi=300, width=500, method=None, waiting=0.5):
         """
         Display a preview of the figure.
 
@@ -284,7 +284,11 @@ def show(self, dpi=300, width=500, method=None):
         This is useful when running unit tests and building the documentation
         in consoles without a Graphical User Interface.
 
-        Note that the external viewer does not block the current process.
+        Note that the external viewer does not block the current process, thus
+        it's necessary to suspend the execution of the current process for a
+        short while after launching the external viewer, so that the preview
+        image won't be deleted before the external viewer tries to open it. Set
+        the ``waiting`` parameter to a larger number if your computer is slow.
 
         Parameters
         ----------
@@ -298,6 +302,10 @@ def show(self, dpi=300, width=500, method=None):
             - **external**: PDF preview in an external program [default]
             - **notebook**: PNG preview [default in Jupyter notebooks]
             - **none**: Disable image preview
+        waiting : float
+            Suspend the execution of the current process for a given number of
+            seconds after launching an external viewer.
+            Only works if ``method="external"``.
         """
         # Module level variable to know which figures had their show method
         # called. Needed for the sphinx-gallery scraper.
@@ -329,7 +337,7 @@ def show(self, dpi=300, width=500, method=None):
 
         if method == "external":
             pdf = self._preview(fmt="pdf", dpi=dpi, anti_alias=False, as_bytes=False)
-            launch_external_viewer(pdf)
+            launch_external_viewer(pdf, waiting=waiting)
 
     def shift_origin(self, xshift=None, yshift=None):
         """