Use ruff to format code snippets in docstrings and remove blackdoc

[seisman]

Description of proposed changes

Since ruff v0.1.8, ruff can format code snippets in docstrings, which can replace the blackdoc tool we're using. See https://astral.sh/blog/ruff-v0.1.8#formatting-code-snippets-in-docstrings for more details. Currently the feature is disabled by default and can be enabled by setting docstring-code-format = true.

Another important setting is docstring-code-line-length, which can be either an integer value or dynamic (default).

Users may also configure the line length limit used for formatting Python code snippets in docstrings. The default, dynamic, instructs the formatter to respect the line length limit setting for the surrounding Python code. dynamic ensures that even when code snippets are found inside indented docstrings, the line length limit configured for the surrounding Python code will be respected.

Users may also configure a fixed line length limit for code snippets in docstrings, which can be useful for ensuring that code snippets in generated documentation adhere to a consistent line length irrespective of the degree of indentation in the originating source code.

I'm still debating what's the most reasonable value for docstring-code-line-length. Here is an example to clarify the differences between "dynamic" and a fixed integer (e.g., 79 or 88).

docstring-code-line-length = 88 gives:

class Test:
    def func(var1, var2, var3):
        """
        >>> func(1234567890, 1234567890, 1234567890, 1234567890, 1234567890, 1234567890, 1234567890)
        """

docstring-code-line-length = "dynamic" gives:

class Test:
    def func(var1, var2, var3):
        """
        >>> func(
        ...     1234567890,
        ...     1234567890,
        ...     1234567890,
        ...     1234567890,
        ...     1234567890,
        ...     1234567890,
        ...     1234567890,
        ... )
        """

Edit:

1. A fixed value for docstring-code-line-length means the actual line length can be longer than 88 characters, which won't work well when viewing the docstrings in text editors/IDEs/Notebooks (see Change the line length limit of docstrings to 88 characters #962).
2. docstring-code-line-length="dynamic" means the doc length won't exceed 88-charcters, which works well in any environment (Change the line length limit of docstrings to 88 characters #962 (comment)).

Related to #962 and #2741.

[codspeed-hq]

CodSpeed Performance Report

Merging #2909 will improve performances by 7.67%

_{Comparing ruff/blackdoc (f4298b5) with main (94e4598)}

Summary

⚡ 1 improvements
✅ 63 untouched benchmarks

Benchmarks breakdown

	Benchmark	main	ruff/blackdoc	Change
⚡	test_grdsample_dataarray_out	113.7 ms	105.6 ms	+7.67%