Update docstrings to use code snippets

Author: Electronic-Mango

src/simplejustwatchapi/justwatch.py

@@ -19,17 +19,20 @@ def search(
     title: str, country: str = "US", language: str = "en", count: int = 4, best_only: bool = True
 ) -> list[MediaEntry]:
     """Search JustWatch for given title.
-    Returns a list of entries up to count.
+    Returns a list of entries up to ``count``.
+    ``best_only`` allows filtering out redundant offers, e.g. when if provide offers service
+    in 4K, HD and SD, using ``best_only = True`` returns only 4K option, ``best_only = False``
+    returns all three.
 
     Args:
         title: title to search
-        country: country to search for offers, "US" by default
-        language: language of responses, "en" by default
+        country: country to search for offers, ``US`` by default
+        language: language of responses, ``en`` by default
         count: how many responses should be returned
-        best_only: return only best offers if True, return all offers if False
+        best_only: return only best offers if ``True``, return all offers if ``False``
 
     Returns:
-        List of MediaEntry NamedTuples parsed from JustWatch response
+        List of ``MediaEntry`` NamedTuples parsed from JustWatch response
     """
     request = prepare_search_request(title, country, language, count, best_only)
     response = post(_GRAPHQL_API_URL, json=request)
@@ -41,12 +44,15 @@ def details(
     node_id: str, country: str = "US", language: str = "en", best_only: bool = True
 ) -> MediaEntry:
     """Get details of entry for a given ID.
+    ``best_only`` allows filtering out redundant offers, e.g. when if provide offers service
+    in 4K, HD and SD, using ``best_only = True`` returns only 4K option, ``best_only = False``
+    returns all three.
 
     Args:
         node_id: ID of entry to look up
-        country: country to search for offers, "US" by default
-        language: language of responses, "en" by default
-        best_only: return only best offers if True, return all offers if False
+        country: country to search for offers, ``US`` by default
+        language: language of responses, ``en`` by default
+        best_only: return only best offers if ``True``, return all offers if ``False``
 
     Returns:
         MediaEntry NamedTuple with data about requested entry.

src/simplejustwatchapi/query.py

@@ -178,15 +178,15 @@ def prepare_search_request(
     title: str, country: str, language: str, count: int, best_only: bool
 ) -> dict:
     """Prepare search request for JustWatch GraphQL API.
-    Creates a "GetSearchTitles" GraphQL query.
+    Creates a ``GetSearchTitles`` GraphQL query.
     Country code should be two uppercase letters, however it will be auto-converted to uppercase.
 
     Args:
         title: title to search
         country: country to search for offers
         language: language of responses
         count: how many responses should be returned
-        best_only: return only best offers if True, return all offers if False
+        best_only: return only best offers if ``True``, return all offers if ``False``
 
     Returns:
         JSON/dict with GraphQL POST body
@@ -211,14 +211,14 @@ def prepare_search_request(
 
 def parse_search_response(json: dict) -> list[MediaEntry]:
     """Parse response from search query from JustWatch GraphQL API.
-    Parses response for "GetSearchTitles" query.
+    Parses response for ``GetSearchTitles`` query.
     If API didn't return any data, then an empty list is returned.
 
     Args:
         json: JSON returned by JustWatch GraphQL API
 
     Returns:
-        Parsed received JSON as a list of MediaEntry NamedTuples
+        Parsed received JSON as a list of ``MediaEntry`` NamedTuples
     """
     nodes = json["data"]["popularTitles"]["edges"]
     entries = [_parse_entry(node["node"]) for node in nodes]
@@ -227,14 +227,14 @@ def parse_search_response(json: dict) -> list[MediaEntry]:
 
 def prepare_details_request(node_id: str, country: str, language: str, best_only: bool) -> dict:
     """Prepare a details request for specified node ID to JustWatch GraphQL API.
-    Creates a "GetTitleNode" GraphQL query.
+    Creates a ``GetTitleNode`` GraphQL query.
     Country code should be two uppercase letters, however it will be auto-converted to uppercase.
 
     Args:
         node_id: node ID of entry to get details for
         country: country to search for offers
         language: language of responses
-        best_only: return only best offers if True, return all offers if False
+        best_only: return only best offers if ``True``, return all offers if ``False``
 
     Returns:
         JSON/dict with GraphQL POST body
@@ -258,16 +258,16 @@ def prepare_details_request(node_id: str, country: str, language: str, best_only
 
 def parse_details_response(json: any) -> MediaEntry | None:
     """Parse response from details query from JustWatch GraphQL API.
-    Parses response for "GetTitleNode" query.
+    Parses response for ``GetTitleNode`` query.
     If API responded with an internal error (mostly due to not found node ID),
-    then "None" will be returned instead.
+    then ``None`` will be returned instead.
 
     Args:
         json: JSON returned by JustWatch GraphQL API
 
     Returns:
-        Parsed received JSON as a MediaEntry NamedTuple,
-        or None in case data for a given node ID was not found
+        Parsed received JSON as a ``MediaEntry`` NamedTuple,
+        or ``None`` in case data for a given node ID was not found
     """
     return _parse_entry(json["data"]["node"]) if "errors" not in json else None