Update api-docs.txt

Author: rich-iannone

pointblank/data/api-docs.txt

@@ -7712,31 +7712,39 @@ table information, and timing details.
 
 send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None' = None, summary_msg: 'str | None' = None, debug: 'bool' = False) -> 'Callable'
 
-    Creates a Slack notification function using a webhook URL.
+    Create a Slack notification function using a webhook URL.
 
     This function can be used in two ways:
 
-    1. With `Actions` to notify about individual validation step failures
-    2. With `FinalActions` to provide a summary after all validation steps complete
+    1. With [`Actions`](`pointblank.Actions`) to notify about individual validation step failures
+    2. With [`FinalActions`](`pointblank.FinalActions`) to provide a summary notification after all
+    validation steps have undergone interrogation
 
     The function creates a callable that sends notifications through a Slack webhook. Message
     formatting can be customized using templates for both individual steps and summary reports.
 
     Parameters
     ----------
     webhook_url
-        The Slack webhook URL. If `None`, performs a dry run.
+        The Slack webhook URL. If `None` (and `debug=True`), a dry run is performed (see the
+        *Offline Testing* section below for information on this).
     step_msg
         Template string for step notifications. Some of the available variables include: `"{step}"`,
         `"{column}"`, `"{value}"`, `"{type}"`, `"{time}"`, `"{level}"`, etc. See the *Available
-        Template Variables for Step Notifications* section below for more details.
+        Template Variables for Step Notifications* section below for more details. If not provided,
+        a default step message template will be used.
     summary_msg
         Template string for summary notifications. Some of the available variables are:
         `"{n_steps}"`, `"{n_passing_steps}"`, `"{n_failing_steps}"`, `"{all_passed}"`,
         `"{highest_severity}"`, etc. See the *Available Template Variables for Summary
-        Notifications* section below for more details.
+        Notifications* section below for more details. If not provided, a default summary message
+        template will be used.
     debug
-        Print debug information and message previews.
+        Print debug information if `True`. This includes the message content and the response from
+        Slack. This is useful for testing and debugging the notification function. If `webhook_url`
+        is `None`, the function will print the message to the console instead of sending it to
+        Slack. This is useful for debugging and ensuring that your templates are formatted
+        correctly.
 
     Returns
     -------
@@ -7761,15 +7769,15 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
     Here's an example of how to construct a `step_msg=` template:
 
     ```python
-    step_msg = \"\"\"🚨 *Validation Step Alert*
+    step_msg = '''🚨 *Validation Step Alert*
     • Step Number: {step}
     • Column: {column}
     • Test Type: {type}
     • Value Tested: {value}
     • Severity: {level} (level {level_num})
     • Brief: {autobrief}
     • Details: {failure_text}
-    • Time: {time}\"\"\"
+    • Time: {time}'''
     ```
 
     This template will be filled with the relevant information when a validation step fails. The
@@ -7799,7 +7807,7 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
     Here's an example of how to put together a `summary_msg=` template:
 
     ```python
-    summary_msg = \"\"\"📊 *Validation Summary Report*
+    summary_msg = '''📊 *Validation Summary Report*
     *Overview*
     • Status: {highest_severity}
     • All Passed: {all_passed}
@@ -7819,7 +7827,7 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
 
     *Timing*
     • Duration: {validation_duration}s
-    • Completed: {time}\"\"\"
+    • Completed: {time}'''
     ```
 
     This template will be filled with the relevant information when the validation summary is
@@ -7829,7 +7837,7 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
     Offline Testing
     ---------------
     If you want to test the function without sending actual notifications, you can leave the
-    `webhook_url` as `None` and set `debug=True`. This will print the message to the console
+    `webhook_url=` as `None` and set `debug=True`. This will print the message to the console
     instead of sending it to Slack. This is useful for debugging and ensuring that your templates
     are formatted correctly. Furthermore, the function could be run globally (i.e., outside of the
     context of a validation plan) to show the message templates with all possible variables. Here's
@@ -7862,17 +7870,17 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
     # Create a Slack notification function with custom templates
     notify_slack = pb.send_slack_notification(
         webhook_url=None, # Leave as None for dry run
-        step_msg=\"\"\"*Data Validation Alert*
+        step_msg='''*Data Validation Alert*
         • Type: {type}
         • Level: {level}
         • Step: {step}
         • Column: {column}
-        • Time: {time}\"\"\",
-        summary_msg=\"\"\"*Data Validation Summary*
+        • Time: {time}''',
+        summary_msg='''*Data Validation Summary*
         • Highest Severity: {highest_severity}
         • Total Steps: {n_steps}
         • Failed Steps: {n_failing_steps}
-        • Time: {time}\"\"\",
+        • Time: {time}''',
         debug=True,  # Enable debug mode to print message previews
     )
     ```
@@ -7883,11 +7891,11 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
 
     Examples
     --------
-    When using an Action with one or more validation steps, you typically provide callables that
+    When using an action with one or more validation steps, you typically provide callables that
     fire when a matched threshold of failed test units is exceeded. The callable can be
     a function or a lambda. The `send_slack_notification()` function creates a callable that sends
     a Slack notification when the validation step fails. Here is how it can be set up to work for
-    multiple validation steps:
+    multiple validation steps by using of [Actions](`pointblank.Actions`):
 
     ```python
     import pointblank as pb
@@ -7917,9 +7925,10 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
     set here, when 15% or more of the test units fail). The notification will include information
     about the validation step that triggered the alert.
 
-    When using a `FinalActions` object, the notification will be sent after all validation steps
-    have been completed. This is useful for providing a summary of the validation process. Here is
-    an example of how to set up a summary notification:
+    When using a [`FinalActions`](`pointblank.FinalActions`) object, the notification will be sent
+    after all validation steps have been completed. This is useful for providing a summary of the
+    validation process. Here is an example of how to set up a summary notification:
+
     ```python
     import pointblank as pb
 
@@ -7960,7 +7969,7 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
 
     notify_slack = pb.send_slack_notification(
         webhook_url="https://hooks.slack.com/services/your/webhook/url",
-        step_msg=\"\"\"
+        step_msg='''
         🚨 *Validation Step Alert*
         • Step Number: {step}
         • Column: {column}
@@ -7969,8 +7978,8 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
         • Severity: {level} (level {level_num})
         • Brief: {autobrief}
         • Details: {failure_text}
-        • Time: {time}\"\"\",
-        summary_msg=\"\"\"
+        • Time: {time}''',
+        summary_msg='''
         📊 *Validation Summary Report*
         *Overview*
         • Status: {highest_severity}
@@ -7991,7 +8000,7 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
 
         *Timing*
         • Duration: {validation_duration}s
-        • Completed: {time}\"\"\",
+        • Completed: {time}''',
     )
 
     # Create a validation plan
@@ -8010,11 +8019,10 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
     ```
 
     In this example, we have customized the templates for both step and summary notifications. The
-    step notification includes details about the validation step, including the step number,
-    column name, test type, value tested, severity level, brief description, and time of the
-    notification. The summary notification includes an overview of the validation process,
-    including the status, number of steps, passing and failing steps, table information, and
-    timing details.
+    step notification includes details about the validation step, including the step number, column
+    name, test type, value tested, severity level, brief description, and time of the notification.
+    The summary notification includes an overview of the validation process, including the status,
+    number of steps, passing and failing steps, table information, and timing details.