From 17fe7a9af78bbbe02346521ce2f408f8f9623be0 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 22 Sep 2020 16:06:33 -0400
Subject: [PATCH] Add docformatter to format docstrings following a subset of
 PEP 257

---
 .github/workflows/ci_tests.yaml | 2 +-
 CONTRIBUTING.md                 | 5 +++--
 Makefile                        | 8 ++++++--
 environment.yml                 | 1 +
 requirements-dev.txt            | 1 +
 5 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ci_tests.yaml b/.github/workflows/ci_tests.yaml
index ac01aaffbda..98e7d4f3629 100644
--- a/.github/workflows/ci_tests.yaml
+++ b/.github/workflows/ci_tests.yaml
@@ -32,7 +32,7 @@ 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)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f874de52ed4..729a2c8a0fd 100644
--- a/CONTRIBUTING.md
+++ b/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 flake8, black, blackdoc, docformatter and isort (in check mode)
 make lint    # Runs pylint, which is a bit slower
 ```
 
diff --git a/Makefile b/Makefile
index 145ddf336d4..e0e7c347700 100644
--- a/Makefile
+++ b/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 --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, isort and flake8)"
 	@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)
diff --git a/environment.yml b/environment.yml
index 1a62bdd5495..ee19928bca7 100644
--- a/environment.yml
+++ b/environment.yml
@@ -21,6 +21,7 @@ dependencies:
     - black
     - blackdoc
     - isort>=5
+    - docformatter
     - pylint
     - flake8
     - sphinx
diff --git a/requirements-dev.txt b/requirements-dev.txt
index fdbbd256aef..3bbe0db9d3f 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -9,6 +9,7 @@ coverage[toml]
 black
 blackdoc
 isort>=5
+docformatter
 pylint
 flake8
 sphinx