docs: update value sharing

Signed-off-by: develop-cs <43383361+develop-cs@users.noreply.github.com>

Author: develop-cs

docs/pages/a_simple_example.md

@@ -106,8 +106,8 @@ An **action** is triggered when the conditions are verified (i.e., `True`).
 **Actions** are defined by the following *keys* in the previous YAML file:
 
 ```yaml
-        action: set_admission  # (1)
-        action_parameters:  # (2)
+        action: set_admission  # (1)!
+        action_parameters:  # (2)!
           value: true  
 ```
 
@@ -201,11 +201,11 @@ Now, let's apply the **rules** on a single applicant:
 ```python
 from arta import RulesEngine
 
-eng = RulesEngine(config_path="/to/my/config/dir")  # (1)
+eng = RulesEngine(config_path="/to/my/config/dir")  # (1)!
 
 result = eng.apply_rules(input_data=applicants[0])
 
-print(result)  # (2)
+print(result)  # (2)!
 # {
 # "admission": {"is_admitted": True},
 # "course": {"course_id": "senior"},

docs/pages/home.md

@@ -12,23 +12,19 @@
 
 Want to discover what is **Arta**? :arrow_right: [Get Started](a_simple_example.md)
 
-
 Want to know how to use it? :arrow_right: [User Guide](how_to.md)
 
-
 !!! info inline "New feature"
 
-    Use **Arta** as a *process execution engine* :zap:
-    
-    Read [this page](rule_activation_mode.md) for more details.
+    Use [value sharing](value_sharing.md) to customize actions and conditions :tools:
 
 !!! tip "Releases"
 
     Check the [Release notes](https://github.com/MAIF/arta/releases) :rocket:
 
-!!! warning "Pydantic 1 compatibility is deprecated"
+!!! warning "Pydantic v1"
 
-    **Arta** is working with [Pydantic 2](https://docs.pydantic.dev/latest/) and Pydantic 1 but compatibility with V1  will be removed in the next **major** release.
+    Compatibility with *Pydantic v1* will be removed in next **major** release.
 
 **Arta** is working and automatically tested with:
 

docs/pages/how_to.md

@@ -43,7 +43,7 @@ rules:
           value: KO
 
 actions_source_modules:
-  - my_folder.actions  # (1)
+  - my_folder.actions  # (1)!
 ```
 
 1. Contains *action function* implementations, no need of the key `conditions_source_modules` here.
@@ -112,10 +112,10 @@ Create a YAML file and define your rules like this:
 ```yaml hl_lines="6 16-26"
 ---
 rules:
-  default_rule_set:  # (1)
+  default_rule_set:  # (1)!
     check_admission:
       ADMITTED_RULE:
-        condition: HAS_SCHOOL_AUTHORIZED_POWER  # (2)
+        condition: HAS_SCHOOL_AUTHORIZED_POWER  # (2)!
         action: set_admission
         action_parameters:
           value: true
@@ -125,16 +125,16 @@ rules:
         action_parameters:
           value: false
 
-conditions:  # (3)
+conditions:  # (3)!
   HAS_SCHOOL_AUTHORIZED_POWER:
     description: "Does applicant have a school authorized power?"
     validation_function: has_authorized_super_power
     condition_parameters:
       power: input.super_power
 
-conditions_source_modules:  # (4)
+conditions_source_modules:  # (4)!
   - my_folder.conditions
-actions_source_modules:  # (5)
+actions_source_modules:  # (5)!
   - my_folder.actions
 ```
 
@@ -289,9 +289,9 @@ A **rule set** is composed of **rule groups** which are themselves composed of *
 ```yaml
 ---
 rules:
-  default_rule_set:  # (1)
-    check_admission:  # (2)
-      ADMITTED_RULE:  # (3)
+  default_rule_set:  # (1)!
+    check_admission:  # (2)!
+      ADMITTED_RULE:  # (3)!
         condition: HAS_SCHOOL_AUTHORIZED_POWER
         action: set_admission
         action_parameters:

docs/pages/value_sharing.md

@@ -1,7 +1,8 @@
-!!! note
+!!! info
 
-    Only available with `arta>=0.10.0`.
+    Needs `arta>=0.10.0`.
 
+## Between conditions and actions
 
 It is possible to share some informations between **condition** and **action** implementations.
 
@@ -22,12 +23,12 @@ In the following example, a **condition** is computing the *median* of some *inp
 def is_median_above(
     values: list[float], 
     limit: float, 
-    **kwargs: Any,  # (1)
+    **kwargs: Any,  # (1)!
     ) -> bool:
     """Check if the median of some values is above limit."""
     median = statistics.median(values)
     # Store the value for later use by an action function
-    kwargs["input_data"]["median"] = median  # (2)
+    kwargs["input_data"]["median"] = median  # (2)!
     kwargs["input_data"]["median_limit"] = limit
     return median > limit
 ```
@@ -39,13 +40,45 @@ def is_median_above(
 **Get the value (in an action for example):**
 
 ```python hl_lines="1 4"
-def alert_on_median(**kwargs: Any) -> str:  # (1)
+def alert_on_median(**kwargs: Any) -> str:  # (1)!
     """Alert: "Median is too high: 13, limit is: 10."""
     return (
-        f"Median is too high: {kwargs['input_data']['median']}, "  # (2)
+        f"Median is too high: {kwargs['input_data']['median']}, "  # (2)!
         f"limit is: {kwargs['input_data']['median_limit']}."
     )
 ```
 
 1. Add the ****kwargs** parameter.
-2. Get the value.
+2. Get the value.
+
+## User extra arguments
+
+The following code shows how to set custom **user extra arguments** (e.g., `add_details`) within the `.apply_rules()` method:
+
+```python hl_lines="5"
+from arta import RulesEngine
+
+eng = RulesEngine(config_path="/to/my/config/dir")
+
+result = eng.apply_rules(input_data={...}, add_details=True)
+```
+
+Used inside **action** and/or **condition functions**:
+
+```python hl_lines="4"
+def my_action(**kwargs: Any) -> str:  # (1)!
+    """A simple action function."""
+
+    if kwargs["add_details"]:  # (2)!
+        action_result = (
+            f"Median is too high: {kwargs['input_data']['median']}, "
+            f"limit is: {kwargs['input_data']['median_limit']}."
+        )
+    else:
+        action_result = "Median is too high."
+    
+    return action_result
+```
+
+1. Don't forget to add the ****kwargs** parameter.
+2. Straight use of the corresponding extra argument.