Add docformatter to format plain text in docstrings (#642)

* Add docformatter to format docstrings following a subset of PEP 257
* Add --make-summary-multi-line
* Install docformatter to make /format work
* Sort dependencies alphabetically in environment.yml and requirements-dev.txt
* Format all docstrings

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

Author: seisman

.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

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
 ```
 

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

pygmt/__init__.py

@@ -67,7 +67,9 @@ def show_versions():
     import sys
 
     def _get_module_version(modname):
-        """Get version information of a Python module."""
+        """
+        Get version information of a Python module.
+        """
         try:
             if modname in sys.modules:
                 module = sys.modules[modname]
@@ -82,7 +84,9 @@ def _get_module_version(modname):
             return None
 
     def _get_ghostscript_version():
-        """Get ghostscript version."""
+        """
+        Get ghostscript version.
+        """
         os_name = sys.platform
         if os_name.startswith("linux") or os_name == "darwin":
             cmds = ["gs"]
@@ -102,7 +106,9 @@ def _get_ghostscript_version():
         return None
 
     def _get_gmt_version():
-        """Get GMT version."""
+        """
+        Get GMT version.
+        """
         try:
             version = subprocess.check_output(
                 ["gmt", "--version"], universal_newlines=True
@@ -164,7 +170,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,6 @@
 """
 Base class with plot generating commands.
+
 Does not define any special non-GMT methods (savefig, show, etc).
 """
 import contextlib
@@ -52,7 +53,6 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
         >>> base = BasePlotting()
         >>> base._preprocess(resolution="low")
         {'resolution': 'low'}
-
         """
         return kwargs
 
@@ -266,7 +266,6 @@ def colorbar(self, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         with Session() as lib:
@@ -295,7 +294,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.
 
@@ -511,7 +510,6 @@ def grdimage(self, grid, **kwargs):
         {p}
         {t}
         {x}
-
         """
         kwargs = self._preprocess(**kwargs)
         kind = data_kind(grid, None, None)
@@ -624,7 +622,6 @@ def grdview(self, grid, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         kind = data_kind(grid, None, None)
@@ -827,7 +824,6 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         {t}
             *transparency* can also be a 1d array to set varying transparency
             for symbols.
-
         """
         kwargs = self._preprocess(**kwargs)
 
@@ -900,7 +896,7 @@ def plot3d(
         self, x=None, y=None, z=None, data=None, sizes=None, direction=None, **kwargs
     ):
         """
-        Plot lines, polygons, and symbols in 3-D
+        Plot lines, polygons, and symbols in 3-D.
 
         Takes a matrix, (x,y,z) triplets, or a file name as input and plots
         lines, polygons, or symbols at those locations in 3-D.
@@ -1010,7 +1006,6 @@ def plot3d(
         {t}
             *transparency* can also be a 1d array to set varying transparency
             for symbols.
-
         """
         kwargs = self._preprocess(**kwargs)
 
@@ -1132,7 +1127,6 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
 
@@ -1208,7 +1202,6 @@ def basemap(self, **kwargs):
         {XY}
         {p}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         if not ("B" in kwargs or "L" in kwargs or "Td" in kwargs or "Tm" in kwargs):
@@ -1267,7 +1260,6 @@ def logo(self, **kwargs):
         {V}
         {XY}
         {t}
-
         """
         kwargs = self._preprocess(**kwargs)
         with Session() as lib:
@@ -1715,17 +1707,20 @@ def meca(
         # pylint: disable=too-many-statements
 
         def set_pointer(data_pointers, spec):
-            """Set optional parameter pointers based on DataFrame or dict, if
-            those parameters are present in the DataFrame or dict."""
+            """
+            Set optional parameter pointers based on DataFrame or dict, if
+            those parameters are present in the DataFrame or dict.
+            """
             for param in list(data_pointers.keys()):
                 if param in spec:
                     # set pointer based on param name
                     data_pointers[param] = spec[param]
 
         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`."""
+            """
+            Updates variables based on the location of data, as the 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

@@ -79,7 +79,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(
@@ -158,7 +157,6 @@ 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
@@ -200,7 +198,6 @@ 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")
@@ -238,7 +235,6 @@ def kwargs_to_ctypes_array(argument, kwargs, dtype):
     ... )
     >>> print(should_be_none)
     None
-
     """
     if argument in kwargs:
         return dtype(*kwargs[argument])

pygmt/clib/loading.py

@@ -30,7 +30,6 @@ def load_libgmt():
     GMTCLibNotFoundError
         If there was any problem loading the library (couldn't find it or
         couldn't access the functions).
-
     """
     lib_fullnames = clib_full_names()
     error = True
@@ -64,7 +63,6 @@ def clib_names(os_name):
     -------
     libnames : list of str
         List of possible names of GMT's shared library.
-
     """
     if os_name.startswith("linux"):
         libnames = ["libgmt.so"]
@@ -93,7 +91,6 @@ def clib_full_names(env=None):
     -------
     lib_fullnames: list of str
         List of possible full names of GMT's shared library.
-
     """
     if env is None:
         env = os.environ
@@ -127,7 +124,6 @@ def check_libgmt(libgmt):
     Raises
     ------
     GMTCLibError
-
     """
     # Check if a few of the functions we need are in the library
     functions = ["Create_Session", "Get_Enum", "Call_Module", "Destroy_Session"]