Add docformatter to format docstrings following a subset of PEP 257

Author: seisman

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

CONTRIBUTING.md

@@ -245,14 +245,16 @@ directory).
 
 ### Code style
 
+<<<<<<< HEAD
 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 +275,11 @@ common errors.
 The [`Makefile`](Makefile) contains rules for running both checks:
 
 ```bash
+<<<<<<< HEAD
 make check   # Runs flake8, black, blackdoc and isort (in check mode)
+=======
+make check   # Runs flake8, black, blackdoc and docformatter (in check mode)
+>>>>>>> f347f709 (Add docformatter to format docstrings following a subset of PEP 257)
 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 --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"
@@ -39,11 +41,13 @@ format:
 	isort .
 	black $(BLACK_FILES)
 	blackdoc $(BLACKDOC_OPTIONS) $(BLACK_FILES)
+	docformatter --in-place $(DOCFORMATTER_OPTIONS) $(DOCFORMATTER_FILES)
 
 check:
 	isort . --check
 	black --check $(BLACK_FILES)
 	blackdoc --check $(BLACKDOC_OPTIONS) $(BLACK_FILES)
+	docformatter --check $(DOCFORMATTER_OPTIONS) $(DOCFORMATTER_FILES)
 	flake8 $(FLAKE8_FILES)
 
 lint:

environment.yml

@@ -21,6 +21,7 @@ dependencies:
     - black
     - blackdoc
     - isort>=5
+    - docformatter
     - pylint
     - flake8
     - sphinx

requirements-dev.txt

@@ -9,6 +9,7 @@ coverage[toml]
 black
 blackdoc
 isort>=5
+docformatter
 pylint
 flake8
 sphinx