docs: haystack.utils docfixes (#7318)

docs/pydoc/config/utils_api.yml

@@ -14,9 +14,9 @@ processors:
   - type: crossref
 renderer:
   type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer
-  excerpt: Utils API
+  excerpt: Utility functions and classes used across the library.
   category_slug: haystack-api
-  title: Utils API
+  title: Utils
   slug: utils-api
   order: 153
   markdown:

haystack/utils/auth.py

@@ -31,7 +31,6 @@ class Secret(ABC):
     from haystack.utils import Secret
 
     generator = OpenAIGenerator(api_key=Secret.from_token("<here_goes_your_token>"))
-    ...
     ```
     """
 

haystack/utils/filters.py

@@ -11,7 +11,9 @@ from haystack.errors import FilterError
 def document_matches_filter(filters: Dict[str, Any], document: Document) -> bool:
     """
     Return whether `filters` match the Document.
-    For a detailed specification of the filters, refer to the DocumentStore.filter_documents() protocol documentation.
+
+    For a detailed specification of the filters, refer to the
+    `DocumentStore.filter_documents()` protocol documentation.
     """
     if "field" in filters:
         return _comparison_condition(filters, document)

haystack/utils/jupyter.py

@@ -5,15 +5,10 @@
 
 def is_in_jupyter() -> bool:
     """
-    Utility function to easily check if we are in a Jupyter or Google Colab environment.
-
-    Inspired by:
-    https://github.com/explosion/spaCy/blob/e1249d3722765aaca56f538e830add7014d20e2a/spacy/util.py#L1079
-
-    Returns True if in Jupyter or Google Colab, False otherwise
+    Returns `True` if in Jupyter or Google Colab, `False` otherwise.
     """
-    #
-    #
+    # Inspired by:
+    # https://github.com/explosion/spaCy/blob/e1249d3722765aaca56f538e830add7014d20e2a/spacy/util.py#L1079
     try:
         # We don't need to import `get_ipython` as it's always present in Jupyter notebooks
         if get_ipython().__class__.__name__ == "ZMQInteractiveShell":  # type: ignore[name-defined]

haystack/utils/requests_utils.py

@@ -11,18 +11,9 @@ def request_with_retry(
     attempts: int = 3, status_codes_to_retry: Optional[List[int]] = None, **kwargs
 ) -> requests.Response:
     """
-    request_with_retry is a simple wrapper function that executes an HTTP request
-    with a configurable exponential backoff retry on failures.
+    Executes an HTTP request with a configurable exponential backoff retry on failures.
 
-    All kwargs will be passed to ``requests.request``, so it accepts the same arguments.
-
-    :param attempts: Maximum number of attempts to retry the request.
-    :param status_codes_to_retry: List of HTTP status codes that will trigger a retry. When param is `None`,  HTTP 408, 418, 429 and 503 will be retried.
-    :param **kwargs: Optional arguments that ``request`` takes.
-    :return: :class:`Response <Response>` object
-
-
-    Usage examples:
+    Usage example:
     ```python
     from haystack.utils import request_with_retry
 
@@ -62,6 +53,16 @@ def request_with_retry(
     # Retry all 5xx status codes
     res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=list(range(500, 600)))
     ```
+
+    :param attempts:
+        Maximum number of attempts to retry the request.
+    :param status_codes_to_retry:
+        List of HTTP status codes that will trigger a retry.
+        When param is `None`, HTTP 408, 418, 429 and 503 will be retried.
+    :param kwargs:
+        Optional arguments that `request` accepts.
+    :returns:
+        The `Response` object.
     """
 
     if status_codes_to_retry is None:

haystack/utils/type_serialization.py

@@ -14,10 +14,12 @@ def serialize_type(target: Any) -> str:
     It assumes that non-typing objects will have a '__name__' attribute and raises
     an error if a type cannot be serialized.
 
-    :param target: The object to serialize, can be an instance or a type.
-    :type target: Any
-    :return: The string representation of the type.
-    :raises ValueError: If the type cannot be serialized.
+    :param target:
+        The object to serialize, can be an instance or a type.
+    :return:
+        The string representation of the type.
+    :raises ValueError:
+        If the type cannot be serialized.
     """
     # If the target is a string and contains a dot, treat it as an already serialized type
     if isinstance(target, str) and "." in target:
@@ -57,11 +59,14 @@ def deserialize_type(type_str: str) -> Any:
     Deserializes a type given its full import path as a string, including nested generic types.
 
     This function will dynamically import the module if it's not already imported
-    and then retrieve the type object from it. It also handles nested generic types like 'typing.List[typing.Dict[int, str]]'.
+    and then retrieve the type object from it. It also handles nested generic types like `typing.List[typing.Dict[int, str]]`.
 
-    :param type_str: The string representation of the type's full import path.
-    :return: The deserialized type object.
-    :raises DeserializationError: If the type cannot be deserialized due to missing module or type.
+    :param type_str:
+        The string representation of the type's full import path.
+    :returns:
+        The deserialized type object.
+    :raises DeserializationError:
+        If the type cannot be deserialized due to missing module or type.
     """
 
     def parse_generic_args(args_str):