Add docformatter to format docstrings following a subset of PEP 257

Author: seisman

.github/workflows/ci_tests.yaml

@@ -28,7 +28,7 @@ jobs:
           python-version: 3.7
 
       - name: Install packages
-        run: pip install black blackdoc flake8 pylint
+        run: pip install black blackdoc docformatter flake8 pylint
 
       - name: Formatting check (black and flake8)
         run: make check

CONTRIBUTING.md

@@ -245,9 +245,10 @@ directory).
 
 ### Code style
 
-We use [Black](https://github.com/ambv/black) and [blackdoc](https://github.com/keewis/blackdoc)
+We use [Black](https://github.com/ambv/black), [blackdoc](https://github.com/keewis/blackdoc)
+and [docformatter](https://github.com/myint/docformatter)
 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:
 
@@ -265,7 +266,7 @@ common errors.
 The [`Makefile`](Makefile) contains rules for running both checks:
 
 ```bash
-make check   # Runs flake8, black and blackdoc (in check mode)
+make check   # Runs flake8, black, blackdoc and docformatter (in check mode)
 make lint    # Runs pylint, which is a bit slower
 ```
 

Makefile

@@ -7,6 +7,8 @@ PYTEST_ARGS=--cov=$(PROJECT) --cov-config=../.coveragerc \
 			--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
 
@@ -15,8 +17,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 and flake8)"
+	@echo "  format    run black, blackdoc and docformatter to automatically format the code"
+	@echo "  check     run code style and quality checks (black, blackdoc, docformatter and flake8)"
 	@echo "  lint      run pylint for a deeper (and slower) quality check"
 	@echo "  clean     clean up build and generated files"
 	@echo ""
@@ -38,10 +40,12 @@ test:
 format:
 	black $(BLACK_FILES)
 	blackdoc $(BLACKDOC_OPTIONS) $(BLACK_FILES)
+	docformatter --in-place $(DOCFORMATTER_OPTIONS) $(DOCFORMATTER_FILES)
 
 check:
 	black --check $(BLACK_FILES)
 	blackdoc --check $(BLACKDOC_OPTIONS) $(BLACK_FILES)
+	docformatter --check $(DOCFORMATTER_OPTIONS) $(DOCFORMATTER_FILES)
 	flake8 $(FLAKE8_FILES)
 
 lint:

environment.yml

@@ -20,6 +20,7 @@ dependencies:
     - coverage
     - black
     - blackdoc
+    - docformatter
     - pylint
     - flake8
     - sphinx=2.2.1

requirements-dev.txt

@@ -8,6 +8,7 @@ pytest-mpl
 coverage
 black
 blackdoc
+docformatter
 pylint
 flake8
 sphinx=2.2.1