Run "make format" to format docstrings

doc/conf.py

@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
-"""
-Sphinx documentation configuration file.
-"""
+"""Sphinx documentation configuration file."""
 # pylint: disable=invalid-name
 
 import datetime

pygmt/__init__.py

@@ -35,8 +35,7 @@
 
 
 def print_clib_info():
-    """
-    Print information about the GMT shared library that we can find.
+    """Print information about the GMT shared library that we can find.
 
     Includes the GMT version, default values for parameters, the path to the
     ``libgmt`` shared library, and GMT directories.
@@ -51,9 +50,8 @@ def print_clib_info():
 
 
 def show_versions():
-    """
-    Prints various dependency versions useful when submitting bug reports. This
-    includes information about:
+    """Prints various dependency versions useful when submitting bug reports.
+    This includes information about:
 
     - PyGMT itself
     - System information (Python version, Operating System)
@@ -136,8 +134,7 @@ def _get_gmt_version():
 
 
 def test(doctest=True, verbose=True, coverage=False, figures=True):
-    """
-    Run the test suite.
+    """Run the test suite.
 
     Uses `pytest <http://pytest.org/>`__ to discover and run the tests. If you
     haven't already, you can install it with `conda
@@ -164,7 +161,6 @@ def test(doctest=True, verbose=True, coverage=False, figures=True):
     AssertionError
         If pytest returns a non-zero error code indicating that some tests have
         failed.
-
     """
     import pytest
 

pygmt/base_plotting.py

@@ -1,5 +1,5 @@
-"""
-Base class with plot generating commands.
+"""Base class with plot generating commands.
+
 Does not define any special non-GMT methods (savefig, show, etc).
 """
 import contextlib
@@ -19,16 +19,14 @@
 
 
 class BasePlotting:
-    """
-    Base class for Figure and Subplot.
+    """Base class for Figure and Subplot.
 
     Defines the plot generating methods and a hook for subclasses to insert
     special arguments (the _preprocess method).
     """
 
     def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
-        """
-        Make any changes to kwargs or required actions before plotting.
+        """Make any changes to kwargs or required actions before plotting.
 
         This method is run before all plotting commands and can be used to
         insert special arguments into the kwargs or make any actions that are
@@ -50,7 +48,6 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
         >>> base = BasePlotting()
         >>> base._preprocess(resolution="low")
         {'resolution': 'low'}
-
         """
         return kwargs
 
@@ -75,8 +72,7 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def coast(self, **kwargs):
-        """
-        Plot continents, shorelines, rivers, and borders on maps
+        """Plot continents, shorelines, rivers, and borders on maps.
 
         Plots grayshaded, colored, or textured land-masses [or water-masses] on
         maps and [optionally] draws coastlines, rivers, and political
@@ -135,7 +131,6 @@ def coast(self, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         with Session() as lib:
@@ -158,8 +153,7 @@ def coast(self, **kwargs):
     )
     @kwargs_to_strings(R="sequence", G="sequence", p="sequence")
     def colorbar(self, **kwargs):
-        """
-        Plot a gray or color scale-bar on maps.
+        """Plot a gray or color scale-bar on maps.
 
         Both horizontal and vertical scales are supported. For CPTs with
         gradational colors (i.e., the lower and upper boundary of an interval
@@ -219,7 +213,6 @@ def colorbar(self, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         with Session() as lib:
@@ -246,8 +239,7 @@ def colorbar(self, **kwargs):
     )
     @kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus", p="sequence")
     def grdcontour(self, grid, **kwargs):
-        """
-        Convert grids or images to contours and plot them on maps
+        """Convert grids or images to contours and plot them on maps.
 
         Takes a grid file name or an xarray.DataArray object as input.
 
@@ -341,8 +333,7 @@ def grdcontour(self, grid, **kwargs):
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def grdimage(self, grid, **kwargs):
-        """
-        Project and plot grids or images.
+        """Project and plot grids or images.
 
         Reads a 2-D grid file and produces a gray-shaded (or colored) map by
         building a rectangular image and assigning pixels a gray-shade (or
@@ -458,7 +449,6 @@ def grdimage(self, grid, **kwargs):
         {p}
         {t}
         {x}
-
         """
         kwargs = self._preprocess(**kwargs)
         kind = data_kind(grid, None, None)
@@ -495,8 +485,7 @@ def grdimage(self, grid, **kwargs):
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def grdview(self, grid, **kwargs):
-        """
-        Create 3-D perspective image or surface mesh from a grid.
+        """Create 3-D perspective image or surface mesh from a grid.
 
         Reads a 2-D grid file and produces a 3-D perspective plot by drawing a
         mesh, painting a colored/gray-shaded surface made up of polygons, or by
@@ -567,7 +556,6 @@ def grdview(self, grid, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         kind = data_kind(grid, None, None)
@@ -614,8 +602,7 @@ def grdview(self, grid, **kwargs):
     )
     @kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
     def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
-        """
-        Plot lines, polygons, and symbols on maps.
+        """Plot lines, polygons, and symbols on maps.
 
         Used to be psxy.
 
@@ -740,8 +727,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
     )
     @kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
     def contour(self, x=None, y=None, z=None, data=None, **kwargs):
-        """
-        Contour table data by direct triangulation.
+        """Contour table data by direct triangulation.
 
         Takes a matrix, (x,y,z) pairs, or a file name as input and plots lines,
         polygons, or symbols at those locations on a map.
@@ -797,7 +783,6 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
 
@@ -834,8 +819,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def basemap(self, **kwargs):
-        """
-        Produce a basemap for the figure.
+        """Produce a basemap for the figure.
 
         Several map projections are available, and the user may specify
         separate tick-mark intervals for boundary annotation, ticking, and
@@ -867,7 +851,6 @@ def basemap(self, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         if not ("B" in kwargs or "L" in kwargs or "T" in kwargs):
@@ -889,8 +872,7 @@ def basemap(self, **kwargs):
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def logo(self, **kwargs):
-        """
-        Place the GMT graphics logo on a map.
+        """Place the GMT graphics logo on a map.
 
         By default, the GMT logo is 2 inches wide and 1 inch high and
         will be positioned relative to the current plot origin.
@@ -915,7 +897,6 @@ def logo(self, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         if "D" not in kwargs:
@@ -937,8 +918,7 @@ def logo(self, **kwargs):
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def image(self, imagefile, **kwargs):
-        """
-        Place images or EPS files on maps.
+        """Place images or EPS files on maps.
 
         Reads an Encapsulated PostScript file or a raster image file and plots
         it on a map.
@@ -990,8 +970,7 @@ def image(self, imagefile, **kwargs):
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwargs):
-        """
-        Plot legends on maps.
+        """Plot legends on maps.
 
         Makes legends that can be overlaid on maps. Reads specific
         legend-related information from an input file, or automatically creates
@@ -1078,8 +1057,7 @@ def text(
         justify=None,
         **kwargs,
     ):
-        """
-        Plot or typeset text strings of variable size, font type, and
+        """Plot or typeset text strings of variable size, font type, and
         orientation.
 
         Must provide at least one of the following combinations as input:
@@ -1239,8 +1217,7 @@ def meca(
         plot_latitude=None,
         **kwargs,
     ):
-        """
-        Plot focal mechanisms.
+        """Plot focal mechanisms.
 
         Full option list at :gmt-docs:`supplements/seis/meca.html`
 
@@ -1342,8 +1319,8 @@ def set_pointer(data_pointers, spec):
 
         def update_pointers(data_pointers):
             """Updates variables based on the location of data, as the
-            following data can be passed as parameters or it can be
-            contained in `spec`."""
+            following data can be passed as parameters or it can be contained
+            in `spec`."""
             # update all pointers
             longitude = data_pointers["longitude"]
             latitude = data_pointers["latitude"]

pygmt/clib/conversion.py

@@ -1,15 +1,12 @@
-"""
-Functions to convert data types into ctypes friendly formats.
-"""
+"""Functions to convert data types into ctypes friendly formats."""
 import numpy as np
 import pandas as pd
 
 from ..exceptions import GMTInvalidInput
 
 
 def dataarray_to_matrix(grid):
-    """
-    Transform an xarray.DataArray into a data 2D array and metadata.
+    """Transform an xarray.DataArray into a data 2D array and metadata.
 
     Use this to extract the underlying numpy array of data and the region and
     increment for the grid.
@@ -80,7 +77,6 @@ def dataarray_to_matrix(grid):
     [-150.5, -78.5, -80.5, -48.5]
     >>> print(inc)
     [2.0, 2.0]
-
     """
     if len(grid.dims) != 2:
         raise GMTInvalidInput(
@@ -119,8 +115,7 @@ def dataarray_to_matrix(grid):
 
 
 def vectors_to_arrays(vectors):
-    """
-    Convert 1d vectors (lists, arrays or pandas.Series) to C contiguous 1d
+    """Convert 1d vectors (lists, arrays or pandas.Series) to C contiguous 1d
     arrays.
 
     Arrays must be in C contiguous order for us to pass their memory pointers
@@ -159,15 +154,13 @@ def vectors_to_arrays(vectors):
     >>> data = [[1, 2], (3, 4), range(5, 7)]
     >>> all(isinstance(i, np.ndarray) for i in vectors_to_arrays(data))
     True
-
     """
     arrays = [as_c_contiguous(np.asarray(i)) for i in vectors]
     return arrays
 
 
 def as_c_contiguous(array):
-    """
-    Ensure a numpy array is C contiguous in memory.
+    """Ensure a numpy array is C contiguous in memory.
 
     If the array is not C contiguous, a copy will be necessary.
 
@@ -201,16 +194,14 @@ def as_c_contiguous(array):
     True
     >>> as_c_contiguous(x).flags.c_contiguous
     True
-
     """
     if not array.flags.c_contiguous:
         return array.copy(order="C")
     return array
 
 
 def kwargs_to_ctypes_array(argument, kwargs, dtype):
-    """
-    Convert an iterable argument from kwargs into a ctypes array variable.
+    """Convert an iterable argument from kwargs into a ctypes array variable.
 
     If the argument is not present in kwargs, returns ``None``.
 
@@ -239,17 +230,15 @@ def kwargs_to_ctypes_array(argument, kwargs, dtype):
     ... )
     >>> print(should_be_none)
     None
-
     """
     if argument in kwargs:
         return dtype(*kwargs[argument])
     return None
 
 
 def array_to_datetime(array):
-    """
-    Convert an 1d datetime array from various types into pandas.DatetimeIndex
-    (i.e., numpy.datetime64).
+    """Convert an 1d datetime array from various types into
+    pandas.DatetimeIndex (i.e., numpy.datetime64).
 
     If the input array is not in legal datetime formats, raise a "ParseError"
     exception.