Merge branch 'master' into common-options-doc-update

.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/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

AUTHORS.md

@@ -8,6 +8,7 @@ Manoa.
 The following people have contributed code to the project (alphabetical by last name)
 and are considered the "PyGMT Developers":
 
+* [Michael Grund](https://github.com/michaelgrund)
 * [Wei Ji Leong](https://github.com/weiji14)
 * [Tyler Newton](http://www.tnewton.com/)
 * [William Schlitzer](https://github.com/willschlitzer)

CONTRIBUTING.md

@@ -249,10 +249,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 +274,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
 ```
 

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017-2020 The PyGMT Developers
+Copyright (c) 2017-2021 The PyGMT Developers
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

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)

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/plot/datetime-inputs.py

@@ -0,0 +1,61 @@
+"""
+Datetime inputs
+---------------
+
+Datetime inputs of the following types are supported in PyGMT:
+
+- :class:`numpy.datetime64`
+- :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"``)
+- 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 the ``x`` and ``y`` arguments
+of e.g. the :meth:`pygmt.Figure.plot` method:
+
+The ``region`` argument has to include the :math:`x` and :math:`y` axis limits as *str* in the form 
+*date_min/date_max/ymin/ymax*.
+
+"""
+
+import datetime
+
+import numpy as np
+import pandas as pd
+import pygmt
+import xarray as xr
+
+fig = pygmt.Figure()
+
+# create a basemap with limits of 2010-01-01 to 2020-06-01 on the x axis and
+# 0 to 10 on the y axis
+fig.basemap(
+    projection="X15c/5c", region="2010-01-01/2020-06-01/0/10", frame=["WSen", "af"]
+)
+
+# numpy.datetime64 types
+x = np.array(["2010-06-01", "2011-06-01T12", "2012-01-01T12:34:56"], dtype="datetime64")
+y = [1, 2, 3]
+fig.plot(x, y, style="c0.4c", pen="1p", color="red3")
+
+# pandas.DatetimeIndex
+x = pd.date_range("2013", periods=3, freq="YS")
+y = [4, 5, 6]
+fig.plot(x, y, style="t0.4c", pen="1p", color="gold")
+
+# xarray.DataArray
+x = xr.DataArray(data=pd.date_range(start="2015-03", periods=3, freq="QS"))
+y = [7.5, 6, 4.5]
+fig.plot(x, y, style="s0.4c", pen="1p")
+
+# raw datetime strings
+x = ["2016-02-01", "2016-06-04T14", "2016-10-04T00:00:15"]
+y = [7, 8, 9]
+fig.plot(x, y, style="a0.4c", pen="1p", color="dodgerblue")
+
+# the Python built-in datetime and date
+x = [datetime.date(2018, 1, 1), datetime.datetime(2019, 6, 1, 20, 5, 45)]
+y = [6.5, 4.5]
+fig.plot(x, y, style="i0.4c", pen="1p", color="seagreen")
+
+fig.show()

examples/gallery/plot/multi-parameter-symbols.py

@@ -3,7 +3,7 @@
 -------------------------
 
 The :meth:`pygmt.Figure.plot` method can plot individual multi-parameter symbols by passing 
-the corresponding shortcuts listed below to the ``style`` option. Additionally, we must define 
+the corresponding shortcuts listed below to the ``style`` argument. Additionally, we must define 
 the required parameters in a 2d list or numpy array (``[[parameters]]`` for a single symbol 
 or ``[[parameters_1],[parameters_2],[parameters_i]]`` for several ones) or use an 
 appropriately formatted input file and pass it to ``data``. 

examples/projections/conic/conic_albers.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Albers Conic Equal Area
 =======================
 
@@ -11,8 +11,12 @@
 Between them, the scale along parallels is too small; beyond them it is too large.
 The opposite is true for the scale along meridians.
 
-``Blon0/lat0/lat1/lat2/width``: Give projection center ``lon0/lat0`` and two standard
-parallels ``lat1/lat2``.
+**b**\ *lon0/lat0*\ /\ *lat1/lat2*\ */scale*
+or **B**\ *lon0/lat0*\ /\ *lat1/lat2*\ */width*
+
+The projection is set with **b** or **B**. The projection center is set by *lon0/lat0*
+and two standard parallels for the map are set with *lat1/lat2*. The figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/conic/conic_equidistant.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Equidistant conic
 =================
 
@@ -7,8 +7,12 @@
 compromise between them. The scale is true along all meridians and the
 standard parallels.
 
-``Dlon0/lat0/lat1/lat2/width``: Give projection center ``lon0/lat0``, two standard
-parallels ``lat1/lat2``, and the map width.
+**d**\ *lon0/lat0*\ /\ *lat1/lat2*\ */scale*
+or **D**\ *lon0/lat0*\ /\ *lat1/lat2*\ */width*
+
+The projection is set with **d** or **D**. The projection center is set by *lon0/lat0*
+and two standard parallels for the map are set with *lat1/lat2*. The figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/conic/conic_lambert.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Lambert Conic Conformal Projection
 ==================================
 
@@ -9,8 +9,12 @@
 with a common origin, and meridians are the equally spaced radii of these circles. As
 with Albers projection, it is only the two standard parallels that are distortion-free.
 
-``Llon0/lat0/lat1/lat2/width``: Give projection center ``lon0/lat0``, two standard
-parallels ``lat1/lat2``, and the map width.
+**l**\ *lon0/lat0*\ /\ *lat1/lat2*\ */scale*
+or **L**\ *lon0/lat0*\ /\ *lat1/lat2*\ */width*
+
+The projection is set with **l** or **L**. The projection center is set by *lon0/lat0*
+and two standard parallels for the map are set with *lat1/lat2*. The figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/conic/polyconic.py

@@ -1,4 +1,4 @@
-"""
+r"""
 Polyconic Projection
 ====================
 
@@ -18,7 +18,10 @@
 consequence, no parallel is standard because conformity is lost with the lengthening of
 the meridians.
 
-``Poly/width``:  The only additional argument for the projection is the map width.
+**poly**\ */scale* or **Poly**\ */width*
+
+The projection is set with **poly** or **Poly**. The figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_cassini.py

@@ -11,7 +11,10 @@
 meridian, each meridian 90° away, and equator are straight lines; all other meridians
 and parallels are complex curves.
 
-``Clon0/lat0/width``: ``lon0`` and ``lat0`` specifies the projection center.
+**c**\ *lon0/lat0*\ */scale* or **C**\ *lon0/lat0*\ */width*
+
+The projection is set with **c** or **C**. The projection center is set by *lon0/lat0*,
+and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_equal_area.py

@@ -6,8 +6,10 @@
 latitude is selected as the standard parallel. However, they are all equal area and
 hence non-conformal. All meridians and parallels are straight lines.
 
-``Ylon0/lat0/width``: Give central meridian ``lon0``, the standard parallel ``lat0``,
-and the figure ``width``.
+**y**\ *lon0/lat0*\ */scale* or **Y**\ *lon0/lat0*\ */width*
+
+The projection is set with **y** or **Y**. The projection center is set by *lon0/lat0*,
+and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_equidistant.py

@@ -6,7 +6,10 @@
 latitudes. The most common form is the Plate Carrée projection, where the scaling of
 longitudes and latitudes is the same. All meridians and parallels are straight lines.
 
-``Qwidth``: Give the figure ``width``.
+**q**\ *scale* or **Q**\ *width*
+
+The projection is set with **q** or **Q**, and the figure size is set
+with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_mercator.py

@@ -12,8 +12,11 @@
 extensively for world maps in which the distortion towards the polar regions grows
 rather large.
 
-``M[lon0/][lat0/]width``: Give central meridian ``lon0`` (optional) and
-standard parallel ``lat0`` (optional).
+**m**\ [*lon0[/lat0]*]\ */scale* or **M**\ [*lon0*][*/lat0*]\ */width*
+
+The projection is set with **m** or **M**. The central meridian is set with the
+option *lon0* and the standard parallel is set with the option *lat0*.
+The figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_miller.py

@@ -9,7 +9,10 @@
 by using Mercator’s formula with 0.8 times the actual latitude, thus avoiding the
 singular poles; the result was then divided by 0.8.
 
-``J[lon0/]width``: Give the optional central meridian ``lon0`` and the figure ``width``.
+**j**\ [*lon0/*]\ */scale* or **J**\ [*lon0/*]\ */width*
+
+The projection is set with **j** or **J**. The central meridian is set by the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_stereographic.py

@@ -10,9 +10,13 @@
 antipodal point on the equator. The cylinder crosses the sphere at two standard
 parallels, equidistant from the equator.
 
-``Cyl_stere/[lon0/][lat0/]width``: Give central meridian ``lon0`` (optional) and
-standard parallel ``lat0`` (optional). The standard parallel is typically one of these
-(but can be any value):
+**cyl_stere/**\ [*lon0/*]\ [*lat0/*]\ *scale*
+or **Cyl_stere/**\ [*lon0/*]\ [*lat0/*]\ *width*
+
+The projection is set with **cyl_stere** or **Cyl_stere**. The central meridian is set
+by the optional *lon0*, and the figure size is set with *scale* or *width*.
+
+The standard parallel is typically one of these (but can be any value):
 
 * 66.159467 - Miller's modified Gall
 * 55 - Kamenetskiy's First

examples/projections/cyl/cyl_transverse_mercator.py

@@ -8,8 +8,11 @@
 center. The central meridian, each meridian 90° away from the center, and equator are
 straight lines; other parallels and meridians are complex curves.
 
-``T[lon0/][lat0/]width``: Give central meridian ``lon0``, the latitude of the
-origin ``lat0`` (optional), and the figure width.
+**t**\ *lon0/*\ [*lat0/*\ ]\ *scale* or **T**\ *lon0/*\ [*lat0/*\ ]\ *width*
+
+The projection is set with **t** or **T**. The central meridian is set
+by  *lon0*, the latitude of the origin is set by the optional *lat0*, and the figure
+size is set with *scale* or *width*.
 """
 import pygmt
 

examples/projections/cyl/cyl_universal_transverse_mercator.py

@@ -14,7 +14,10 @@
 1 part in 1,000 from true scale at equator. The ellipsoidal projection expressions are
 accurate for map areas that extend less than 10 away from the central meridian.
 
-``U[UTM Zone/][lat0/]width``: Give UTM Zone ``UTM Zone``, and the figure width.
+**u**\ *zone/scale* or **U**\ *zone/width*
+
+the projection is set with **u** or **U**. *zone* sets the zone for the figure, and
+the figure size is set wtih *scale* or *width*.
 """
 import pygmt
 

examples/projections/misc/misc_eckertIV.py

@@ -7,8 +7,10 @@
 meridian and all parallels are straight lines; other meridians are equally spaced
 elliptical arcs. The scale is true along latitude 40°30’.
 
-``Kf[central meridian]/width``: Give the optional central meridian (default is the
-center of the region) and the map width.
+**kf**\ [*lon0/*]\ *scale* or **Kf**\ [*lon0/*]\ *width*
+
+The projection is set with **kf** or **Kf**. The central meridian is set with the
+optional *lon0*, and the figure size is set with *scale* or *width*.
 """
 import pygmt