Documenation updates (#1790)

* Documentation updates

* More doc changes

* Update docs/docs/examples.rst

Fixed link

Author: yoavkatz

docs/docs/examples.rst

@@ -90,9 +90,9 @@ This example demonstrates how to evaluate model tool calling capabilities.  It r
 a set of user textual requests and corresponding reference answers as tool calls.
 The model is expected to generate tool calls and these are compared to the references.
 
-`Example code <https://github.com/IBM/unitxt/blob/main/examples/tool_call_evaluation.py>`__
+`Example code <https://github.com/IBM/unitxt/blob/main/examples/evaluate_tool_calling.py>`__
 
-Related documentation: :ref:`Tool calling task in catalog <catalog.tasks.tool_calling.supervised>`,:ref:`Tool calling tutorial <tool_calling>`,
+Related documentation: :ref:`Tool calling task in catalog <catalog.tasks.tool_calling.supervised>`, :ref:`Tool calling tutorial <tool_calling>`
 
 
 Evaluate API Call 
@@ -106,7 +106,7 @@ using  the standard key_value_extraction metric.
 
 `Example code <https://github.com/IBM/unitxt/blob/main/examples/api_call_evaluation.py>`__
 
-Related documentation: :ref:`Key Value Extraction metric in catalog <catalog.metrics.key_value_extraction>`,:ref:`Templates tutorial <adding_template>`,
+Related documentation: :ref:`Key Value Extraction metric in catalog <catalog.metrics.key_value_extraction>`, :ref:`Templates tutorial   <adding_template>`
 
 Evaluate using Unitxt metrics on existing predictions
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++

src/unitxt/operators.py

@@ -324,6 +324,21 @@ def recursive_key_value_replace(data, target_key, value_map, value_remove=None):
     return data
 
 class RecursiveReplace(InstanceOperator):
+    # Assisted by watsonx Code Assistant
+    """An operator to recursively replace values in dictionary fields of instances based on a key and a mapping of values.
+
+    Attributes:
+        key (str): The key in the dictionary to start the replacement process.
+        map_values (dict): A dictionary containing the key-value pairs to replace the original values.
+        remove_values (Optional[list]): An optional list of values to remove from the dictionary. Defaults to None.
+
+    Example:
+    RecursiveReplace(key="a", map_values={"1": "hi", "2": "bye" }, remove_values=["3"])
+        replaces the value of key "a" in all instances of all streams:
+        instance ``{"field" : [{"a": "1", "b" : "2"}, {"a" : "3", "b:" "4"}}` becomes ``{"field" : [{"a": "hi", "b" : "2"}, {"b": "4"}}``
+
+        Notice how the value of field ``"a"`` in the first instance is replaced with ``"hi"`` and the value of field ``"a"`` in the second instance is removed.
+    """
     key: str
     map_values: dict
     remove_values: Optional[list] = None
@@ -605,10 +620,27 @@ class AddConstant(FieldOperator):
     def process_value(self, value: Any) -> Any:
         return self.add + value
 
-
 class ShuffleFieldValues(FieldOperator):
-    """Shuffles a list of values found in a field."""
+    # Assisted by watsonx Code Assistant
+    """An operator that shuffles the values of a list field.
+
+    the seed for shuffling in the is determined by the elements of the input field,
+    ensuring that the shuffling operation produces different results for different input lists,
+    but also that it is deterministic and reproducible.
+
+    Attributes:
+        None
 
+    Methods:
+        process_value(value: Any) -> Any:
+            Shuffles the elements of the input list and returns the shuffled list.
+
+            Parameters:
+                value (Any): The input list to be shuffled.
+
+    Returns:
+                Any: The shuffled list.
+    """
     def process_value(self, value: Any) -> Any:
         res = list(value)
         random_generator = new_random_generator(sub_seed=res)
@@ -945,7 +977,14 @@ class CopyFields(Copy):
 
 
 class GetItemByIndex(FieldOperator):
-    """Get from the item list by the index in the field."""
+    """Get the element from the fixed list by the index in the given field and store in another field.
+
+    Example:
+        GetItemByIndex(items_list=["dog",cat"],field="animal_index",to_field="animal")
+
+    on instance {"animal_index" : 1}  will change the instance to {"animal_index" : 1, "animal" : "cat"}
+
+    """
 
     items_list: List[Any]