From 7de62abc917ccb0ec3be54628dea9ff8c99f42a0 Mon Sep 17 00:00:00 2001
From: maang-h <55082429+maang-h@users.noreply.github.com>
Date: Sun, 4 Aug 2024 01:44:09 +0800
Subject: [PATCH] docs: Standardize SparkLLMTextEmbeddings docstrings (#25021)

- **Description:** Standardize SparkLLMTextEmbeddings docstrings
- **Issue:** the issue #24856
---
 .../embeddings/sparkllm.py                    | 65 +++++++++++++++----
 1 file changed, 53 insertions(+), 12 deletions(-)

diff --git a/libs/community/langchain_community/embeddings/sparkllm.py b/libs/community/langchain_community/embeddings/sparkllm.py
index d8578810f8..01aad6be11 100644
--- a/libs/community/langchain_community/embeddings/sparkllm.py
+++ b/libs/community/langchain_community/embeddings/sparkllm.py
@@ -40,26 +40,67 @@ class Url:
 
 
 class SparkLLMTextEmbeddings(BaseModel, Embeddings):
-    """SparkLLM Text Embedding models.
+    """SparkLLM embedding model integration.
 
-    To use, you should have the environment variable "SPARK_APP_ID","SPARK_API_KEY"
-    and "SPARK_API_SECRET" set your APP_ID, API_KEY and API_SECRET or pass it
-    as a name parameter to the constructor.
+    Setup:
+        To use, you should have the environment variable "SPARK_APP_ID","SPARK_API_KEY"
+        and "SPARK_API_SECRET" set your APP_ID, API_KEY and API_SECRET or pass it
+        as a name parameter to the constructor.
+
+        .. code-block:: bash
+
+            export SPARK_APP_ID="your-api-id"
+            export SPARK_API_KEY="your-api-key"
+            export SPARK_API_SECRET="your-api-secret"
+
+    Key init args — completion params:
+        api_key: Optional[str]
+            Automatically inferred from env var `SPARK_API_KEY` if not provided.
+        app_id: Optional[str]
+            Automatically inferred from env var `SPARK_APP_ID` if not provided.
+        api_secret: Optional[str]
+            Automatically inferred from env var `SPARK_API_SECRET` if not provided.
+        base_url: Optional[str]
+            Base URL path for API requests.
+
+    See full list of supported init args and their descriptions in the params section.
+
+    Instantiate:
 
-    Example:
         .. code-block:: python
 
             from langchain_community.embeddings import SparkLLMTextEmbeddings
 
-            embeddings = SparkLLMTextEmbeddings(
-                spark_app_id="your-app-id",
-                spark_api_key="your-api-key",
-                spark_api_secret="your-api-secret"
+            embed = SparkLLMTextEmbeddings(
+                api_key="...",
+                app_id="...",
+                api_secret="...",
+                # other
             )
-            text = "This is a test query."
-            query_result = embeddings.embed_query(text)
 
-    """
+    Embed single text:
+        .. code-block:: python
+
+            input_text = "The meaning of life is 42"
+            embed.embed_query(input_text)
+
+        .. code-block:: python
+
+            [-0.4912109375, 0.60595703125, 0.658203125, 0.3037109375, 0.6591796875, 0.60302734375, ...]
+
+    Embed multiple text:
+        .. code-block:: python
+
+            input_texts = ["This is a test query1.", "This is a test query2."]
+            embed.embed_documents(input_texts)
+
+        .. code-block:: python
+
+            [
+                [-0.1962890625, 0.94677734375, 0.7998046875, -0.1971435546875, 0.445556640625, 0.54638671875, ...],
+                [  -0.44970703125, 0.06585693359375, 0.7421875, -0.474609375, 0.62353515625, 1.0478515625, ...],
+            ]
+    """  # noqa: E501
 
     spark_app_id: Optional[SecretStr] = Field(default=None, alias="app_id")
     """Automatically inferred from env var `SPARK_APP_ID` if not provided."""