doc: Update documentation to account for Black/ruff

Author: DarkaMaul

Diff for: docs/.glossary.md

@@ -8,5 +8,6 @@
 [Spacy's documentation]: https://spacy.io/api/doc/
 [Black]: https://pypi.org/project/black/ 
 [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material
+[Ruff]: https://docs.astral.sh/ruff
 
 *[ToC]: Table of Contents

Diff for: docs/schema.json

@@ -145,7 +145,7 @@
               "default": false
             },
             "separate_signature": {
-              "title": "Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it.",
+              "title": "Whether to put the whole signature in a code block below the heading. If a formatter (Black or Ruff) is installed, the signature is also formatted using it.",
               "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#separate_signature",
               "type": "boolean",
               "default": false

Diff for: docs/usage/configuration/signatures.md

@@ -154,10 +154,15 @@ def convert(text: str, md: Markdown) -> Markup:
 Maximum line length when formatting code/signatures.
 
 When separating signatures from headings with the [`separate_signature`][] option,
-the Python handler will try to format the signatures using [Black] and
+the Python handler will try to format the signatures using a formatter and
 the specified line length.
 
-If Black is not installed, the handler issues an INFO log once.
+The handler will automatically try to format using :
+
+1. [Black]
+2. [Ruff]
+
+If a formatter is not found, the handler issues an INFO log once.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -380,10 +385,15 @@ function(param1, param2=None)
 Whether to put the whole signature in a code block below the heading.
 
 When separating signatures from headings,
-the Python handler will try to format the signatures using [Black] and
+the Python handler will try to format the signatures using a formatter and
 the specified [line length][line_length].
 
-If Black is not installed, the handler issues an INFO log once.
+The handler will automatically try to format using :
+
+1. [Black]
+2. [Ruff]
+
+If a formatter is not found, the handler issues an INFO log once.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:

Diff for: src/mkdocstrings_handlers/python/handler.py

@@ -201,7 +201,7 @@ class PythonHandler(BaseHandler):
         show_signature_annotations (bool): Show the type annotations in methods and functions signatures. Default: `False`.
         signature_crossrefs (bool): Whether to render cross-references for type annotations in signatures. Default: `False`.
         separate_signature (bool): Whether to put the whole signature in a code block below the heading.
-            If Black is installed, the signature is also formatted using it. Default: `False`.
+            If a formatter (Black or Ruff) is installed, the signature is also formatted using it. Default: `False`.
         unwrap_annotated (bool): Whether to unwrap `Annotated` types to show only the type without the annotations. Default: `False`.
         modernize_annotations (bool): Whether to modernize annotations, for example `Optional[str]` into `str | None`. Default: `False`.
     """

Diff for: src/mkdocstrings_handlers/python/rendering.py

@@ -72,11 +72,11 @@ def _sort_key_source(item: CollectorItem) -> Any:
 
 
 def do_format_code(code: str, line_length: int) -> str:
-    """Format code using Black.
+    """Format code.
 
     Parameters:
         code: The code to format.
-        line_length: The line length to give to Black.
+        line_length: The line length.
 
     Returns:
         The same code, formatted.
@@ -138,13 +138,13 @@ def do_format_signature(
     annotations: bool | None = None,
     crossrefs: bool = False,  # noqa: ARG001
 ) -> str:
-    """Format a signature using Black.
+    """Format a signature.
 
     Parameters:
         context: Jinja context, passed automatically.
         callable_path: The path of the callable we render the signature of.
         function: The function we render the signature of.
-        line_length: The line length to give to Black.
+        line_length: The line length.
         annotations: Whether to show type annotations.
         crossrefs: Whether to cross-reference types in the signature.
 
@@ -200,13 +200,13 @@ def do_format_attribute(
     *,
     crossrefs: bool = False,  # noqa: ARG001
 ) -> str:
-    """Format an attribute using Black.
+    """Format an attribute.
 
     Parameters:
         context: Jinja context, passed automatically.
         attribute_path: The path of the callable we render the signature of.
         attribute: The attribute we render the signature of.
-        line_length: The line length to give to Black.
+        line_length: The line length.
         crossrefs: Whether to cross-reference types in the signature.
 
     Returns:
@@ -443,7 +443,7 @@ def _get_formatter() -> Callable[[str, int], str]:
         if (formatter := formatter_function()) is not None:
             return formatter
 
-    logger.info("Formatting signatures requires either Black or ruff to be installed.")
+    logger.info("Formatting signatures requires either Black or Ruff to be installed.")
     return lambda text, _: text
 
 
@@ -461,7 +461,7 @@ def _get_ruff_formatter() -> Callable[[str, int], str] | None:
     def formatter(code: str, line_length: int) -> str:
         try:
             completed_process = subprocess.run(  # noqa: S603
-                [  # noqa: S607
+                [
                     ruff_bin,
                     "format",
                     "--config",

Diff for: tests/test_rendering.py

@@ -31,7 +31,7 @@
     ],
 )
 def test_format_code(code: str, formatter: Callable[[str, int], str]) -> None:
-    """Assert code can be Black-formatted.
+    """Assert code can be formatted.
 
     Parameters:
         code: Code to format.
@@ -45,7 +45,7 @@ def test_format_code(code: str, formatter: Callable[[str, int], str]) -> None:
     [("Class.method", "(param: str = 'hello') -> 'OtherClass'")],
 )
 def test_format_signature(name: Markup, signature: str) -> None:
-    """Assert signatures can be Black-formatted.
+    """Assert signatures can be formatted.
 
     Parameters:
         signature: Signature to format.