Use ruff to format code snippets in docstrings and remove blackdoc (#2909)

Author: seisman

.github/workflows/format-command.yml

@@ -32,7 +32,7 @@ jobs:
       # Install formatting tools
       - name: Install formatting tools
         run: |
-          python -m pip install blackdoc docformatter ruff
+          python -m pip install docformatter ruff
           python -m pip list
           sudo apt-get install dos2unix
 

.github/workflows/style_checks.yaml

@@ -34,11 +34,11 @@ jobs:
 
       - name: Install packages
         run: |
-          python -m pip install blackdoc docformatter ruff
+          python -m pip install docformatter ruff
           python -m pip list
           sudo apt-get install dos2unix
 
-      - name: Formatting check (blackdoc, docformatter, ruff)
+      - name: Formatting check (docformatter, ruff)
         run: make check
 
       - name: Ensure files use UNIX line breaks and have 644 permission

Makefile

@@ -15,8 +15,8 @@ help:
 	@echo "  fulltest       run the test suite (including all doctests)"
 	@echo "  doctest        run the doctests only"
 	@echo "  test_no_images run the test suite (including all doctests) but skip image comparisons"
-	@echo "  format         run blackdoc, docformatter and ruff to automatically format the code"
-	@echo "  check          run code style and quality checks (blackdoc, docformatter, ruff)"
+	@echo "  format         run docformatter and ruff to automatically format the code"
+	@echo "  check          run code style and quality checks (docformatter and ruff)"
 	@echo "  codespell      run codespell to check common misspellings"
 	@echo "  typecheck      run mypy for static type check"
 	@echo "  clean          clean up build and generated files"
@@ -61,13 +61,11 @@ test_no_images: _runtest
 
 format:
 	docformatter --in-place $(FORMAT_FILES)
-	blackdoc $(FORMAT_FILES)
 	ruff check --fix $(FORMAT_FILES)
 	ruff format $(FORMAT_FILES)
 
 check:
 	docformatter --check $(FORMAT_FILES)
-	blackdoc --check $(FORMAT_FILES)
 	ruff check $(FORMAT_FILES)
 	ruff format --check $(FORMAT_FILES)
 

doc/contributing.md

@@ -473,7 +473,6 @@ code, be sure to follow the general guidelines in the
 
 We use some tools to format the code so we don't have to think about it:
 
-- [blackdoc](https://github.com/keewis/blackdoc)
 - [docformatter](https://github.com/myint/docformatter)
 - [ruff](https://docs.astral.sh/ruff)
 
@@ -512,7 +511,7 @@ The [`Makefile`](https://github.com/GenericMappingTools/pygmt/blob/main/Makefile
 contains rules for running the linter checks:
 
 ```bash
-make check   # Runs blackdoc, docformatter, ruff (in check mode)
+make check   # Runs docformatter and ruff (in check mode)
 ```
 
 ### Testing your Code

environment.yml

@@ -23,10 +23,9 @@ dependencies:
     - make
     - pip
     # Dev dependencies (style checks)
-    - blackdoc
     - codespell
     - docformatter>=1.7.2
-    - ruff
+    - ruff>=0.1.9
     # Dev dependencies (unit testing)
     - matplotlib
     - pytest-cov

pygmt/accessors.py

@@ -57,9 +57,7 @@ class GMTDataArrayAccessor:
     >>> lon = np.arange(0, 360 + interval, interval)
     >>> longrid, latgrid = np.meshgrid(lon, lat)
     >>> data = np.sin(np.deg2rad(longrid)) * np.cos(np.deg2rad(latgrid))
-    >>> grid = xr.DataArray(
-    ...     data, coords=[("latitude", lat), ("longitude", lon)]
-    ... )
+    >>> grid = xr.DataArray(data, coords=[("latitude", lat), ("longitude", lon)])
     >>> # default to a gridline-registrated Cartesian grid
     >>> grid.gmt.registration, grid.gmt.gtype
     (0, 0)

pygmt/clib/session.py

@@ -140,7 +140,6 @@ class Session:
     ...             ses.call_module("grdinfo", f"{fin} -C ->{fout.name}")
     ...             # Read the contents of the temp file before it's deleted.
     ...             print(fout.read().strip())
-    ...
     -55 -47 -24 -10 190 981 1 1 8 14 1 1
     """
 
@@ -305,7 +304,6 @@ def get_libgmt_func(self, name, argtypes=None, restype=None):
         ...     func = lib.get_libgmt_func(
         ...         "GMT_Destroy_Session", argtypes=[c_void_p], restype=c_int
         ...     )
-        ...
         >>> type(func)
         <class 'ctypes.CDLL.__init__.<locals>._FuncPtr'>
         """
@@ -546,13 +544,11 @@ def get_common(self, option):
         ...     lib.call_module("plot", "-T -Xw+1i -Yh-1i")
         ...     xshift = lib.get_common("X")  # xshift/yshift are in inches
         ...     yshift = lib.get_common("Y")
-        ...
         >>> print(region, projection, timestamp, verbose, xshift, yshift)
         [ 0. 10. 10. 15.] True False 3 6.0 1.5
         >>> with Session() as lib:
         ...     lib.call_module("basemap", "-R0/10/10/15 -JX5i/2.5i -Baf")
         ...     lib.get_common("A")
-        ...
         Traceback (most recent call last):
         ...
         pygmt.exceptions.GMTInvalidInput: Unknown GMT common option flag 'A'.
@@ -816,13 +812,11 @@ def _check_dtype_and_dim(self, array, ndim):
         >>> with Session() as ses:
         ...     gmttype = ses._check_dtype_and_dim(data, ndim=1)
         ...     gmttype == ses["GMT_DOUBLE"]
-        ...
         True
         >>> data = np.ones((5, 2), dtype="float32")
         >>> with Session() as ses:
         ...     gmttype = ses._check_dtype_and_dim(data, ndim=2)
         ...     gmttype == ses["GMT_FLOAT"]
-        ...
         True
         """
         # Check that the array has the given number of dimensions
@@ -1150,7 +1144,6 @@ def open_virtual_file(self, family, geometry, direction, data):
         ...             args = f"{vfile} ->{ofile.name}"
         ...             lib.call_module("info", args)
         ...             print(ofile.read().strip())
-        ...
         <vector memory>: N = 5 <0/4> <5/9>
         """
         c_open_virtualfile = self.get_libgmt_func(
@@ -1241,7 +1234,6 @@ def virtualfile_from_vectors(self, *vectors):
         ...         with GMTTempFile() as fout:
         ...             ses.call_module("info", f"{fin} ->{fout.name}")
         ...             print(fout.read().strip())
-        ...
         <vector memory>: N = 3 <1/3> <4/6> <7/9>
         """
         # Conversion to a C-contiguous array needs to be done here and not in
@@ -1350,7 +1342,6 @@ def virtualfile_from_matrix(self, matrix):
         ...         with GMTTempFile() as fout:
         ...             ses.call_module("info", f"{fin} ->{fout.name}")
         ...             print(fout.read().strip())
-        ...
         <matrix memory>: N = 4 <0/9> <1/10> <2/11>
         """
         # Conversion to a C-contiguous array needs to be done here and not in
@@ -1432,7 +1423,6 @@ def virtualfile_from_grid(self, grid):
         ...             args = f"{fin} -L0 -Cn ->{fout.name}"
         ...             ses.call_module("grdinfo", args)
         ...             print(fout.read().strip())
-        ...
         -55 -47 -24 -10 190 981 1 1 8 14 1 1
         >>> # The output is: w e s n z0 z1 dx dy n_columns n_rows reg gtype
         """
@@ -1520,14 +1510,11 @@ def virtualfile_from_data(  # noqa: PLR0912
         ...     ),
         ... )
         >>> with Session() as ses:
-        ...     with ses.virtualfile_from_data(
-        ...         check_kind="vector", data=data
-        ...     ) as fin:
+        ...     with ses.virtualfile_from_data(check_kind="vector", data=data) as fin:
         ...         # Send the output to a file so that we can read it
         ...         with GMTTempFile() as fout:
         ...             ses.call_module("info", fin + " ->" + fout.name)
         ...             print(fout.read().strip())
-        ...
         <vector memory>: N = 3 <7/9> <4/6> <1/3>
         """
         kind = data_kind(
@@ -1623,20 +1610,16 @@ def extract_region(self):
         ... )
         >>> with Session() as lib:
         ...     wesn = lib.extract_region()
-        ...
         >>> print(", ".join([f"{x:.2f}" for x in wesn]))
         0.00, 10.00, -20.00, -10.00
 
         Using ISO country codes for the regions (for example ``"US.HI"`` for
         Hawaiʻi):
 
         >>> fig = pygmt.Figure()
-        >>> fig.coast(
-        ...     region="US.HI", projection="M6i", frame=True, land="black"
-        ... )
+        >>> fig.coast(region="US.HI", projection="M6i", frame=True, land="black")
         >>> with Session() as lib:
         ...     wesn = lib.extract_region()
-        ...
         >>> print(", ".join([f"{x:.2f}" for x in wesn]))
         -164.71, -154.81, 18.91, 23.58
 
@@ -1645,12 +1628,9 @@ def extract_region(self):
         region to multiples of 5):
 
         >>> fig = pygmt.Figure()
-        >>> fig.coast(
-        ...     region="US.HI+r5", projection="M6i", frame=True, land="black"
-        ... )
+        >>> fig.coast(region="US.HI+r5", projection="M6i", frame=True, land="black")
         >>> with Session() as lib:
         ...     wesn = lib.extract_region()
-        ...
         >>> print(", ".join([f"{x:.2f}" for x in wesn]))
         -165.00, -150.00, 15.00, 25.00
         """  # noqa: RUF002

pygmt/datasets/earth_free_air_anomaly.py

@@ -92,9 +92,7 @@ def load_earth_free_air_anomaly(
     >>> # load the default grid (gridline-registered 1 arc-degree grid)
     >>> grid = load_earth_free_air_anomaly()
     >>> # load the 30 arc-minutes grid with "gridline" registration
-    >>> grid = load_earth_free_air_anomaly(
-    ...     resolution="30m", registration="gridline"
-    ... )
+    >>> grid = load_earth_free_air_anomaly(resolution="30m", registration="gridline")
     >>> # load high-resolution (5 arc-minutes) grid for a specific region
     >>> grid = load_earth_free_air_anomaly(
     ...     resolution="05m",

pygmt/datasets/earth_magnetic_anomaly.py

@@ -119,9 +119,7 @@ def load_earth_magnetic_anomaly(
     >>> # load the default grid (gridline-registered 1 arc-degree grid)
     >>> grid = load_earth_magnetic_anomaly()
     >>> # load the 30 arc-minutes grid with "gridline" registration
-    >>> grid = load_earth_magnetic_anomaly(
-    ...     resolution="30m", registration="gridline"
-    ... )
+    >>> grid = load_earth_magnetic_anomaly(resolution="30m", registration="gridline")
     >>> # load high-resolution (5 arc-minutes) grid for a specific region
     >>> grid = load_earth_magnetic_anomaly(
     ...     resolution="05m",

pygmt/helpers/decorators.py

@@ -421,7 +421,6 @@ def fmt_docstring(module_func):
     ...     {aliases}
     ...     '''
     ...     pass
-    ...
     >>> print(gmtinfo.__doc__)
     <BLANKLINE>
     My nice module.
@@ -526,7 +525,6 @@ def use_alias(**aliases):
     >>> @use_alias(R="region", J="projection")
     ... def my_module(**kwargs):
     ...     print("R =", kwargs["R"], "J =", kwargs["J"])
-    ...
     >>> my_module(R="bla", J="meh")
     R = bla J = meh
     >>> my_module(region="bla", J="meh")
@@ -641,9 +639,7 @@ def kwargs_to_strings(**conversions):
 
     Examples
     --------
-    >>> @kwargs_to_strings(
-    ...     R="sequence", i="sequence_comma", files="sequence_space"
-    ... )
+    >>> @kwargs_to_strings(R="sequence", i="sequence_comma", files="sequence_space")
     ... def module(*args, **kwargs):
     ...     "A module that prints the arguments it received"
     ...     print("{", end="")
@@ -813,7 +809,6 @@ def deprecate_parameter(oldname, newname, deprecate_version, remove_version):
     ... def module(data, size=0, **kwargs):
     ...     "A module that prints the arguments it received"
     ...     print(f"data={data}, size={size}, color={kwargs['color']}")
-    ...
     >>> # new names are supported
     >>> module(data="table.txt", size=5.0, color="red")
     data=table.txt, size=5.0, color=red
@@ -825,13 +820,11 @@ def deprecate_parameter(oldname, newname, deprecate_version, remove_version):
     ...     for i in range(len(w)):
     ...         assert issubclass(w[i].category, FutureWarning)
     ...         assert "deprecated" in str(w[i].message)
-    ...
     data=table.txt, size=5.0, color=red
     >>> # using both old and new names will raise an GMTInvalidInput exception
     >>> import pytest
     >>> with pytest.raises(GMTInvalidInput):
     ...     module(data="table.txt", size=5.0, sizes=4.0)
-    ...
     """
 
     def deprecator(module_func):