Unpin docformatter 1.5.1

[weiji14]

Description of proposed changes

Docformatter=1.7.0 has a --black option to make it compatible with the black linter. Also updated a few docstrings in the unit test where docformatter tried to capitalize the first letter.

Thanks @seisman for checking the docformatter 1.7.0 RC releases too at PyCQA/docformatter#199!

Reverts #2482, resolves #2476.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[weiji14]

Yeah, let's keep docformatter pinned to 1.5.1 for a while. The latest docformatter=1.7.1 is removing some newlines from the .py files under examples/. E.g.

diff --git a/examples/gallery/histograms/scatter_and_histograms.py b/examples/gallery/histograms/scatter_and_histograms.py
index 2c414f7e7..872b4e0d1 100644
--- a/examples/gallery/histograms/scatter_and_histograms.py
+++ b/examples/gallery/histograms/scatter_and_histograms.py
@@ -1,11 +1,11 @@
 """
-Scatter plot with histograms
-----------------------------
-To create a scatter plot with histograms at the sides of the plot one
-can use :meth:`pygmt.Figure.plot` in combination with
-:meth:`pygmt.Figure.histogram`. The positions of the histograms are plotted
-by offseting them from the main scatter plot figure using
-:meth:`pygmt.Figure.shift_origin`.
+Scatter plot with histograms ---------------------------- To create a scatter
+plot with histograms at the sides of the plot one can use
+:meth:`pygmt.Figure.plot` in combination with :meth:`pygmt.Figure.histogram`.
+
+The positions of the histograms are plotted by offseting them from the main
+scatter plot figure using
+:meth: `pygmt.Figure.shift_origin`.
 """
 
 import numpy as np
diff --git a/examples/projections/azim/azim_equidistant.py b/examples/projections/azim/azim_equidistant.py
index 2b75b9266..bee76ffcd 100644

Looking at https://github.com/PyCQA/docformatter/issues, it looks like they're sorting out some issues with whitespace and newlines, so give them a few days.

[weibullguy]

Also updated a few docstrings in the unit test where docformatter tried to capitalize the first letter.

FYI, there is a --non-cap argument that takes a list of words to not capitalize when they appear as the first word in the summary. Thus:

docformatter --non-cap grdcut grdproject psconvert <List of files>

shouldn't capitalize those words in your docstrings. Or set this list in your pyproject.toml:

[tool.docformatter]
black = true
recursive = true
pre-summary-newline = true
make-summary-multi-line = true
non-cap = [
	"grdcut",
        "grdproject",
        "psconvert",
]

[weiji14]

Style checks passing now with docformatter=1.7.2 (thanks @weibullguy for pushing out the patch release!). Made a small edit to remove some whitespaces at ddade3e.