feat: [AAP-38755] add documentation for event filter plugins

.config/dictionary.txt

@@ -5,6 +5,7 @@ AUTHS
 Abhijeet
 Alina
 Buzachis
+Doston
 EDAHTTP
 FQCN
 GSSAPI
@@ -13,6 +14,7 @@ Nikhil
 OAUTHBEARER
 PYTHONUNBUFFERED
 Passw
+Toirov
 akasurde
 alertmanager
 alinabuzachis
@@ -34,6 +36,7 @@ darglint
 deadsnakes
 digestmod
 docsite
+dtoirov
 dynatrace
 envlist
 extfile

extensions/eda/plugins/event_filter/dashes_to_underscores.py

@@ -1,12 +1,16 @@
-"""dashes_to_underscores.py.
-
-    An event filter that changes dashes in keys to underscores.
-    For instance, the key X-Y becomes the new key X_Y.
-
-Arguments:
----------
-    * overwrite: Overwrite the values if there is a collision with a new key.
-
+DOCUMENTATION = r"""
+---
+author:
+  - Doston Toirov (@dtoirov)
+short_description: Change dashes to underscores.
+description:
+  - An event filter that changes dashes in keys to underscores. For instance, the key X-Y becomes the new key X_Y.
+options:
+  overwrite:
+    description:
+      - Overwrite the values if there is a collision with a new key.
+    type: bool
+    default: true
 """
 
 import multiprocessing as mp

extensions/eda/plugins/event_filter/insert_hosts_to_meta.py

@@ -1,38 +1,59 @@
-"""insert_hosts_to_meta.py.
-
-An ansible-rulebook event filter that extract hosts from the event data and
-insert them to the meta dict. Ansible-rulebook will limit an ansible action
-running on hosts in the meta dict.
-
-Arguments:
----------
-    host_path:      The json path inside the event data to find hosts.
-                    Do nothing if the key is not present or does exist in event
-    path_separator: The separator to interpret host_path. Default to "."
-    host_separator: The separator to interpret host string.
-                    host_path can point to a string or a list. If it is a single
-                    string but contains multiple hosts, use this parameter to
-                    delimits the hosts. Treat the vale as a single host if the
-                    parameter is not present.
-    raise_error:    Whether raise PathNotExistError if host_path does not
-                    exist in the event. Default to false.
-                    It is recommended to turn it on during the rulebook
-                    development time. You can then turn it off for production.
-    log_error:      Whether log an error message if host_path does not
-                    exist in the event. Default to true.
-                    You can turn if off if it is expected to have events not
-                    having the host_path to avoid noises in the log.
-
-Example:
--------
-    filters:
-      - ansible.eda.insert_hosts_to_meta:
-          host_path: "app.target"
-          path_separator: "."
-          host_separator: ";"
-          raise_error: true
-          log_error: true
+DOCUMENTATION = r"""
+---
+author:
+  - Doston Toirov (@dtoirov)
+short_description: Extract hosts from the event data and insert them to the meta dict.
+description:
+  - An ansible-rulebook event filter that extracts hosts from the event data and
+    inserts them to the meta dict. Ansible-rulebook will limit an ansible action
+    running on hosts in the meta dict.
+options:
+  host_path:
+    description:
+      - The json path inside the event data to find hosts.
+      - Do nothing if the key is not present or does exist in event.
+    type: str
+    default: null
+  path_separator:
+    description:
+      - The separator to interpret host_path.
+    type: str
+    default: "."
+  host_separator:
+    description:
+      - The separator to interpret host string.
+      - host_path can point to a string or a list. If it is a single
+        string but contains multiple hosts, use this parameter to
+        delimits the hosts. Treat the value as a single host if the
+        parameter is not present.
+    type: str
+    default: null
+  raise_error:
+    description:
+      - Whether raise PathNotExistError if host_path does not
+        exist in the event.
+      - It is recommended to turn it on during the rulebook
+        development time. You can then turn it off for production.
+    type: bool
+    default: false
+  log_error:
+    description:
+      - Whether log an error message if host_path does not
+        exist in the event.
+      - You can turn if off if it is expected to have events not
+        having the host_path to avoid noises in the log.
+    type: bool
+    default: true
+"""
 
+EXAMPLES = r"""
+filters:
+  - ansible.eda.insert_hosts_to_meta:
+      host_path: "app.target"
+      path_separator: "."
+      host_separator: ";"
+      raise_error: true
+      log_error: true
 """
 
 from __future__ import annotations

extensions/eda/plugins/event_filter/json_filter.py

@@ -1,16 +1,25 @@
-"""json_filter.py:   An event filter that filters keys out of events.
-
-Includes override excludes.
-
-This is useful to exclude information from events that is unneeded by the rule
-engine.
-
-Arguments:
----------
-    * exclude_keys = a list of strings or patterns to remove
-    * include_keys = a list of strings or patterns to keep even if it matches
-    exclude_keys patterns.
-
+DOCUMENTATION = r"""
+---
+author:
+  - Doston Toirov (@dtoirov)
+short_description: Filter keys out of events.
+description:
+  - An event filter that filters keys out of events.
+    Includes override excludes.
+    This is useful to exclude information from events that is unneeded by the rule engine.
+options:
+  exclude_keys:
+    description:
+      - A list of strings or patterns to remove.
+    type: list
+    elements: str
+    default: null
+  include_keys:
+    description:
+      - A list of strings or patterns to keep even if it matches exclude_keys patterns.
+    type: list
+    elements: str
+    default: null
 """
 
 from __future__ import annotations

extensions/eda/plugins/event_filter/noop.py

@@ -1,4 +1,11 @@
-"""noop.py:   An event filter that does nothing to the input."""
+DOCUMENTATION = r"""
+---
+author:
+  - Doston Toirov (@dtoirov)
+short_description: Do nothing.
+description:
+  - An event filter that does nothing to the input.
+"""
 
 from typing import Any
 

extensions/eda/plugins/event_filter/normalize_keys.py

@@ -1,40 +1,40 @@
-"""normalize_keys.py.
-
-    An event filter that changes keys that contain non alpha numeric or
+DOCUMENTATION = r"""
+---
+author:
+  - Doston Toirov (@dtoirov)
+short_description: Change keys that contain non-alpha numeric or underscore to underscores.
+description: |
+  - An event filter that changes keys that contain non alpha numeric or
     underscore to underscores.
-    For instance, the key server-name becomes the new key server_name
-    If there are consecutive non alpa numeric or under score, they would
-    be coalesced into a single underscore
+  - For instance, the key server-name becomes the new key server_name.
+    If there are consecutive non alpha numeric or under score, they would
+    be coalesced into a single underscore.
     For instance the key server.com/&abc becomes server_com_abc
     instead of server_com__abc.
+  - If there is a existing key with the normalized name, it will get overwritten
+    by default. If you don't want to over write it you can pass in "overwrite: false"
+    The default value of overwrite is true.
+options:
+  overwrite:
+    description:
+      - Overwrite the values if there is a collision with a new key.
+    type: bool
+    default: true
+"""
 
-    If there is a existing key with the normalized name, it will get overwritten
-    by default. If you don't want to over write it you can pass in overwrite: False
-    The default value of overwrite is True.
-
-Arguments:
----------
-    * overwrite: Overwrite the values if there is a collision with a new key.
-
-Usage in a rulebook, a filter is usually attached to a source in the rulebook:
-    example1:
-    ....
-    sources:
-      - my_source:
-         ....
-        filters:
-          ansible.eda.normalize_keys:
-
-
-    example2: To prevent over writing of keys
-    ....
-    sources:
-      - my_source:
-         ....
-        filters:
-          ansible.eda.normalize_keys:
-            overwrite: False
-
+EXAMPLES = r"""
+- sources:
+    - my_source:
+        ....
+      filters:
+        ansible.eda.normalize_keys:
+- name: prevent overwriting of keys
+  sources:
+    - my_source:
+        ....
+      filters:
+        ansible.eda.normalize_keys:
+          overwrite: false
 """
 
 import logging