From 49e877f9291d1d699d6e6f4eb1bcda081111edab Mon Sep 17 00:00:00 2001
From: Bo Maryniuk <bo@maryniuk.net>
Date: Thu, 24 Oct 2024 21:51:28 +0200
Subject: [PATCH] Add documentation for pipescript event handler

---
 docs/evthandlers/overview.rst   |  1 +
 docs/evthandlers/pipescript.rst | 80 +++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 docs/evthandlers/pipescript.rst

diff --git a/docs/evthandlers/overview.rst b/docs/evthandlers/overview.rst
index 7f07d32d..104d16bb 100644
--- a/docs/evthandlers/overview.rst
+++ b/docs/evthandlers/overview.rst
@@ -10,6 +10,7 @@ Event Handlers
 
    console_logger
    outcome_logger
+   pipescript
 
 Overview
 --------
diff --git a/docs/evthandlers/pipescript.rst b/docs/evthandlers/pipescript.rst
new file mode 100644
index 00000000..28950c24
--- /dev/null
+++ b/docs/evthandlers/pipescript.rst
@@ -0,0 +1,80 @@
+Pipe Script
+===========
+
+.. note::
+
+    This document explains how to use **pipescript** event handler.
+
+Synopsis
+--------
+
+.. code-block:: text
+    :caption: Initialisation
+
+    handler:
+        - pipescript
+
+*Pipescript* handler is used to pipe action's response through any script, using STDIN.
+User can define what to do with this information further.
+
+.. important::
+
+    This handler will react only if action contains return code ``0``, i.e. handler has
+    a proper response data structure. Otherwise handler will skip the process and
+    will log an error.
+
+Options
+-------
+
+``program``
+^^^^^^^^^^
+
+    A full command line what needs to be called in event of writing STDIN to the program. Example:
+
+    .. code-block:: yaml
+        :caption: Program definition
+
+        program: "/path/to/my/script.pl --some=argument --quiet"
+
+``quiet``
+^^^^^^^^^^^
+
+    **Optional.** Mute logging. Example:
+
+    .. code-block:: yaml
+        :caption: Mute logging
+
+        quiet: true
+
+``format``
+^^^^^^^^^^
+
+In what format output needs to be sent to the target program. Options:
+
+    - ``yaml``
+    - ``json``
+
+Example:
+
+    .. code-block:: yaml
+        :caption: Format definition
+
+        format: json # or "yaml"
+
+Example
+-------
+
+.. code-block:: yaml
+    :caption: Setup example
+
+    events:
+      # React only on action-wise successful events
+      $/$/$/0:
+
+        handlers:
+          pipescript
+
+        pipescript:
+          program: /opt/bin/extra-logger.pl
+          quiet: false
+          format: json