Merge branch 'master' into test-grdimage-dvc

Author: weiji14

.github/workflows/cache_data.yaml

@@ -19,7 +19,7 @@ jobs:
     steps:
       # Setup Miniconda
       - name: Setup Miniconda
-        uses: conda-incubator/[email protected].0
+        uses: conda-incubator/[email protected].1
         with:
           channels: conda-forge
           miniconda-version: "latest"

.github/workflows/ci_docs.yml

@@ -56,7 +56,7 @@ jobs:
 
       # Setup Miniconda
       - name: Setup Miniconda
-        uses: conda-incubator/[email protected].0
+        uses: conda-incubator/[email protected].1
         with:
           activate-environment: pygmt
           python-version: ${{ matrix.python-version }}
@@ -68,7 +68,7 @@ jobs:
         run: |
           conda install gmt=6.1.1 numpy pandas xarray netCDF4 packaging \
                         ipython make myst-parser \
-                        sphinx sphinx-copybutton sphinx-gallery sphinx_rtd_theme=0.5.1
+                        sphinx sphinx-copybutton sphinx-gallery sphinx_rtd_theme
 
       # Show installed pkg information for postmortem diagnostic
       - name: List installed packages

.github/workflows/ci_tests.yaml

@@ -76,7 +76,7 @@ jobs:
 
       # Setup Miniconda
       - name: Setup Miniconda
-        uses: conda-incubator/[email protected].0
+        uses: conda-incubator/[email protected].1
         with:
           activate-environment: pygmt
           python-version: ${{ matrix.python-version }}
@@ -140,7 +140,7 @@ jobs:
 
       # Upload coverage to Codecov
       - name: Upload coverage to Codecov
-        uses: codecov/[email protected].1
+        uses: codecov/[email protected].2
         with:
           file: ./coverage.xml # optional
           env_vars: OS,PYTHON,NUMPY

.github/workflows/ci_tests_dev.yaml

@@ -73,7 +73,7 @@ jobs:
 
       # Setup Miniconda
       - name: Setup Miniconda
-        uses: conda-incubator/[email protected].0
+        uses: conda-incubator/[email protected].1
         with:
           activate-environment: pygmt
           python-version: ${{ matrix.python-version }}

CONTRIBUTING.md

@@ -187,8 +187,11 @@ When editing documentation, use the following standards to demonstrate the examp
    (two asterisks) on both sides. The argument description should be in *italicized*
    with \* (single asterisk) on both sides.
    Examples: `**+l**\ *label*` results in **+l***label*, `**05m**` results in **05m**.
-3. Optional arguments are placed wrapped with [ ] (square brackets).
+3. Optional arguments are wrapped with [ ] (square brackets).
 4. Arguments that are mutually exclusive are separated with a | (bar) to denote "or".
+5. Default arguments for parameters and configuration settings are wrapped
+   with [ ] (square brackers) with the prefix "Default is". Example: [Default is
+   **p**].
 
 ## Contributing Code
 

MANIFEST.in

@@ -7,7 +7,6 @@ exclude .gitignore
 exclude .pylintrc
 exclude AUTHORSHIP.md
 exclude CONTRIBUTING.md
-exclude MAINTENANCE.md
 exclude Makefile
 exclude environment.yml
 exclude package.json

Makefile

@@ -36,7 +36,7 @@ test:
 	@echo ""
 	@cd $(TESTDIR); python -c "import $(PROJECT); $(PROJECT).show_versions()"
 	@echo ""
-	cd $(TESTDIR); pytest $(PYTEST_COV_ARGS) $(PROJECT)
+	cd $(TESTDIR); PYGMT_USE_EXTERNAL_DISPLAY="false" pytest $(PYTEST_COV_ARGS) $(PROJECT)
 	cp $(TESTDIR)/coverage.xml .
 	cp -r $(TESTDIR)/htmlcov .
 	rm -r $(TESTDIR)

doc/Makefile

@@ -31,7 +31,8 @@ html: api
 	@echo
 	@echo "Building HTML files."
 	@echo
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	# Set PYGMT_USE_EXTERNAL_DISPLAY to "false" to disable external display
+	PYGMT_USE_EXTERNAL_DISPLAY="false" $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

doc/_static/style.css

@@ -89,6 +89,32 @@ p {
     max-width: 1000px;
 }
 
+/* Format parameters section similar to sphinx_rtd_theme v4.x.x (not a grid) */
+html.writer-html5 .rst-content dl.field-list {
+    display: initial;
+}
+
+/* Add a grey box around parameters similar to sphinx_rtd_theme v4.x.x) */
+.rst-content dl:not(.docutils) dl dt {
+    margin-bottom: 4px;
+    border: none;
+    border-left: solid 3px #ccc;
+    background: #f0f0f0;
+    color: #555;
+}
+
+.rst-content dl:not(.docutils) dt {
+    display: table;
+    margin: 6px 0;
+    font-size: 90%;
+    line-height: normal;
+    background: #e7f2fa;
+    color: #2980B9;
+    border-top: solid 3px #6ab0de;
+    padding: 6px;
+    position: relative;
+}
+
 /* Remove the padding from the Parameters table */
 .rst-content table.field-list .field-name {
     padding-left: 0px;

doc/api/index.rst

@@ -60,6 +60,13 @@ Saving and displaying the figure:
     Figure.show
     Figure.psconvert
 
+Configuring the display settings:
+
+.. autosummary::
+    :toctree: generated
+
+    set_display
+
 
 Data Processing
 ---------------

doc/conf.py

@@ -78,6 +78,7 @@
             "../examples/gallery/3d_plots",
             "../examples/gallery/seismology",
             "../examples/gallery/basemaps",
+            "../examples/gallery/histograms",
             "../examples/gallery/embellishments",
             "../examples/projections/azim",
             "../examples/projections/conic",
@@ -150,7 +151,14 @@
 html_theme_options = {}
 repository = "GenericMappingTools/pygmt"
 repository_url = "https://github.com/GenericMappingTools/pygmt"
-commit_link = f'<a href="{repository_url}/commit/{ __commit__ }">{ __commit__[:8] }</a>'
+if __commit__:
+    commit_link = (
+        f'<a href="{repository_url}/commit/{ __commit__ }">{ __commit__[:8] }</a>'
+    )
+else:
+    commit_link = (
+        f'<a href="{repository_url}/releases/tag/{ __version__ }">{ __version__ }</a>'
+    )
 html_context = {
     "menu_links": [
         (

doc/index.rst

@@ -49,4 +49,5 @@
     :caption: Reference documentation
 
     api/index.rst
-    changes.rst
+    changes.md
+    maintenance.md

MAINTENANCE.md renamed to doc/maintenance.md

@@ -4,30 +4,17 @@ This page contains instructions for project maintainers about how our setup work
 making releases, creating packages, etc.
 
 If you want to make a contribution to the project, see the
-[Contributing Guide](CONTRIBUTING.md) instead.
-
-## Table of Contents
-* [Onboarding Access Checklist](#onboarding-access-checklist)
-* [Branches](#branches)
-* [Reviewing and Merging Pull Requests](#reviewing-and-merging-pull-requests)
-* [Continuous Integration](#continuous-integration)
-* [Continuous Documentation](#continuous-documentation)
-* [Dependencies Policy](#dependencies-policy)
-* [Making a Release](#making-a-release)
-    - [Updating the Changelog](#updating-the-changelog)
-    - [Check the README Syntax](#check-the-readme-syntax)
-    - [Pushing to PyPI and Updating the Documentation](#pushing-to-pypi-and-updating-the-documentation)
-    - [Archiving on Zenodo](#archiving-on-zenodo)
-    - [Updating the Conda Package](#updating-the-conda-package)
+[Contributing Guide](https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md)
+instead.
 
 ## Onboarding Access Checklist
 
-- [ ] Added to [python-maintainers](https://github.com/orgs/GenericMappingTools/teams/python-maintainers) team in the [GenericMappingTools](https://github.com/orgs/GenericMappingTools/teams/) organization on GitHub (gives 'maintain' permissions)
-- [ ] Added as collaborator on [DAGsHub](https://dagshub.com/GenericMappingTools/pygmt/settings/collaboration) (gives 'write' permission to dvc remote storage)
-- [ ] Added as moderator on [GMT forum](https://forum.generic-mapping-tools.org) (to see mod-only discussions)
-- [ ] Added as member on the [PyGMT devs Slack channel](https://pygmtdevs.slack.com) (for casual conversations)
-- [ ] Added as maintainer on [PyPI](https://pypi.org/project/pygmt/) and [Test PyPI](https://test.pypi.org/project/pygmt) [optional]
-- [ ] Added as member on [HackMD](https://hackmd.io/@pygmt) [optional]
+- Added to [python-maintainers](https://github.com/orgs/GenericMappingTools/teams/python-maintainers) team in the [GenericMappingTools](https://github.com/orgs/GenericMappingTools/teams/) organization on GitHub (gives 'maintain' permissions)
+- Added as collaborator on [DAGsHub](https://dagshub.com/GenericMappingTools/pygmt/settings/collaboration) (gives 'write' permission to dvc remote storage)
+- Added as moderator on [GMT forum](https://forum.generic-mapping-tools.org) (to see mod-only discussions)
+- Added as member on the [PyGMT devs Slack channel](https://pygmtdevs.slack.com) (for casual conversations)
+- Added as maintainer on [PyPI](https://pypi.org/project/pygmt/) and [Test PyPI](https://test.pypi.org/project/pygmt) [optional]
+- Added as member on [HackMD](https://hackmd.io/@pygmt) [optional]
 
 ## Branches
 

environment.yml

@@ -32,4 +32,4 @@ dependencies:
     - sphinx
     - sphinx-copybutton
     - sphinx-gallery
-    - sphinx_rtd_theme=0.5.1
+    - sphinx_rtd_theme

examples/gallery/embellishments/logo.py

@@ -2,7 +2,7 @@
 Logo
 ----
 
-The :meth:`pygmt.Figure.logo` method allows to place the GMT logo on a map.  
+The :meth:`pygmt.Figure.logo` method allows to place the GMT logo on a map.
 """
 
 import pygmt

examples/gallery/histograms/README.txt

@@ -0,0 +1,2 @@
+Histograms
+----------

examples/gallery/embellishments/rose.py renamed to examples/gallery/histograms/rose.py

@@ -8,8 +8,8 @@
 
 A *pen* in GMT has three attributes: *width*, *color*, and *style*.
 The *style* attribute controls the appearance of the line.
-Giving “dotted” or “.” yields a dotted line, whereas a dashed pen is requested
-with “dashed” or “-”. Also combinations of dots and dashes, like “.-” for a
+Giving "dotted" or "." yields a dotted line, whereas a dashed pen is requested
+with "dashed" or "-". Also combinations of dots and dashes, like ".-" for a
 dot-dashed line, are allowed.
 
 For more advanced *pen* attributes, see the GMT cookbook

examples/gallery/lines/linestyles.py

@@ -11,8 +11,8 @@
 * **3** = Marine boundaries
 * **a** = All boundaries (1-3)
 
-For example, to draw national boundaries with a line thickness of 1p and black line 
-color use ``borders="1/1p,black"``. You can draw multiple boundaries by passing in 
+For example, to draw national boundaries with a line thickness of 1p and black line
+color use ``borders="1/1p,black"``. You can draw multiple boundaries by passing in
 a list to ``borders``.
 """
 import pygmt

examples/gallery/maps/borders.py

@@ -2,7 +2,7 @@
 Color land and water
 --------------------
 
-The ``land`` and ``water`` parameters of :meth:`pygmt.Figure.coast` specify 
+The ``land`` and ``water`` parameters of :meth:`pygmt.Figure.coast` specify
 a color to fill in the land and water masses, respectively. There are many
 :gmt-docs:`color codes in GMT <gmtcolors.html>`, including standard GMT color
 names (like ``skyblue``), R/G/B levels (like ``0/0/255``), a hex value (like

examples/gallery/maps/land_and_water.py

@@ -8,14 +8,14 @@
 - :class:`pandas.DatetimeIndex`
 - :class:`xarray.DataArray`: datetimes included in a *xarray.DataArray*
 - raw datetime strings in `ISO format <https://en.wikipedia.org/wiki/ISO_8601>`__
-  (e.g. ``"YYYY-MM-DD"``, ``"YYYY-MM-DDTHH"``, and ``"YYYY-MM-DDTHH:MM:SS"``) 
+  (e.g. ``"YYYY-MM-DD"``, ``"YYYY-MM-DDTHH"``, and ``"YYYY-MM-DDTHH:MM:SS"``)
 - Python built-in :class:`datetime.datetime` and :class:`datetime.date`
 
-We can pass datetime inputs based on one of the types listed above directly to 
+We can pass datetime inputs based on one of the types listed above directly to
 the ``x`` and ``y`` parameters of e.g. the :meth:`pygmt.Figure.plot` method.
 
-The ``region`` parameter has to include the :math:`x` and :math:`y` axis limits 
-in the form [*date_min*, *date_max*, *ymin*, *ymax*]. Here *date_min* and 
+The ``region`` parameter has to include the :math:`x` and :math:`y` axis limits
+in the form [*date_min*, *date_max*, *ymin*, *ymax*]. Here *date_min* and
 *date_max* can be directly defined as datetime input.
 
 """

examples/gallery/symbols/datetime_inputs.py

@@ -6,7 +6,7 @@
 Arthur H. Robinson in 1963, is a modified cylindrical projection that is neither
 conformal nor equal-area. Central meridian and all parallels are straight lines; other
 meridians are curved. It uses lookup tables rather than analytic expressions to make
-the world map “look” right 22. The scale is true along latitudes 38. The projection was
+the world map "look" right 22. The scale is true along latitudes 38. The projection was
 originally developed for use by Rand McNally and is currently used by the
 National Geographic Society.
 

examples/projections/misc/misc_robinson.py

@@ -4,7 +4,7 @@
 
 The sinusoidal projection is one of the oldest known projections, is equal-area, and
 has been used since the mid-16th century. It has also been called the
-“Equal-area Mercator” projection. The central meridian is a straight line; all other
+"Equal-area Mercator" projection. The central meridian is a straight line; all other
 meridians are sinusoidal curves. Parallels are all equally spaced straight lines, with
 scale being true along all parallels (and central meridian).
 

examples/projections/misc/misc_sinusoidal.py

@@ -4,9 +4,9 @@
 
 In 1921, the German mathematician Oswald Winkel a projection that was to strike a
 compromise between the properties of three elements (area, angle and distance). The
-German word “tripel” refers to this junction of where each of these elements are least
+German word "tripel" refers to this junction of where each of these elements are least
 distorted when plotting global maps. The projection was popularized when Bartholomew
-and Son started to use it in its world-renowned “The Times Atlas of the World” in the
+and Son started to use it in its world-renowned "The Times Atlas of the World" in the
 mid-20th century. In 1998, the National Geographic Society made the Winkel Tripel as
 its map projection of choice for global maps.
 

examples/projections/misc/misc_winkel_tripel.py

@@ -3,7 +3,7 @@
 =====
 
 Polar projections allow plotting polar coordinate data (e.g. angle
-:math:`\theta` and radius *r*). 
+:math:`\theta` and radius *r*).
 
 The full syntax for polar projections is:
 

examples/projections/nongeo/polar.py

@@ -251,7 +251,7 @@
 
 ########################################################################################
 # Plot Circular Vectors
-# ----------
+# ---------------------
 #
 # When plotting circular vectors, all of the information for a single vector is
 # to be stored in a list. Each circular vector list is structured as:

examples/tutorials/vectors.py

@@ -25,7 +25,7 @@
 # Import modules to make the high-level GMT Python API
 from pygmt import datasets
 from pygmt.accessors import GMTDataArrayAccessor
-from pygmt.figure import Figure
+from pygmt.figure import Figure, set_display
 from pygmt.session_management import begin as _begin
 from pygmt.session_management import end as _end
 from pygmt.src import (
@@ -47,7 +47,7 @@
 
 # Get semantic version through setuptools-scm
 __version__ = f'v{get_distribution("pygmt").version}'  # e.g. v0.1.2.dev3+g0ab3cd78
-__commit__ = __version__.split("+g")[-1]  # 0ab3cd78
+__commit__ = __version__.split("+g")[-1] if "+g" in __version__ else ""  # 0ab3cd78
 
 # Start our global modern mode session
 _begin()

pygmt/__init__.py

@@ -10,7 +10,7 @@
 from pygmt.src import grdcut, which
 
 
-@kwargs_to_strings(convert_bools=False, region="sequence")
+@kwargs_to_strings(region="sequence")
 def load_earth_relief(resolution="01d", region=None, registration=None, use_srtm=False):
     r"""
     Load Earth relief grids (topography and bathymetry) in various resolutions.