feat: [AAP-38755] add documentation for alertmanager, aws_cloudtrail and aws_sqs_queue plugins

.config/dictionary.txt

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

extensions/eda/plugins/event_filter/dashes_to_underscores.py

@@ -3,8 +3,6 @@
 
 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.

extensions/eda/plugins/event_filter/insert_hosts_to_meta.py

@@ -7,8 +7,6 @@
 
 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

extensions/eda/plugins/event_filter/json_filter.py

@@ -5,8 +5,6 @@
 
 DOCUMENTATION = r"""
 ---
-author:
-  - Doston Toirov (@dtoirov)
 short_description: Filter keys out of events.
 description:
   - An event filter that filters keys out of events.

extensions/eda/plugins/event_filter/noop.py

@@ -2,8 +2,6 @@
 
 DOCUMENTATION = r"""
 ---
-author:
-  - Doston Toirov (@dtoirov)
 short_description: Do nothing.
 description:
   - An event filter that does nothing to the input.

extensions/eda/plugins/event_filter/normalize_keys.py

@@ -5,8 +5,6 @@
 
 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

extensions/eda/plugins/event_source/alertmanager.py

@@ -1,44 +1,63 @@
-"""alertmanager.py.
-
-An ansible-rulebook event source module for receiving events via a webhook from
-alertmanager or alike system.
-
-Arguments:
----------
-    host: The webserver hostname to listen to. Set to 0.0.0.0 to listen on all
-          interfaces. Defaults to localhost
-    port: The TCP port to listen to.  Defaults to 5000
-    data_alerts_path: The json path to find alert data. Default to "alerts"
-                      Use empty string "" to treat the whole payload data as
-                      one alert.
-    data_host_path: The json path inside the alert data to find alerting host.
-                    Use empty string "" if there is no need to find host.
-                    Default to  "labels.instance".
-    data_path_separator: The separator to interpret data_host_path and
-                         data_alerts_path. Default to "."
-    skip_original_data: true/false. Default to false
-                        true: put only alert data to the queue
-                        false: put sequentially both the received original
-                               data and each parsed alert item to the queue.
-
-Example:
--------
-    - ansible.eda.alertmanager:
-        host: 0.0.0.0
-        port: 8000
-        data_alerts_path: alerts
-        data_host_path: labels.instance
-        data_path_separator: .
-
-"""
-
 import asyncio
 import logging
 from typing import Any
 
 from aiohttp import web
 from dpath import util
 
+DOCUMENTATION = r"""
+---
+short_description: Receive events via a webhook from alertmanager or a compatible alerting system.
+description:
+  - An ansible-rulebook event source module for receiving events via a webhook from alertmanager
+    or a compatible alerting system.
+options:
+  host:
+    description:
+      - The webserver hostname to listen to. Set to 0.0.0.0 to listen on all
+        interfaces.
+    type: str
+    default: "localhost"
+  port:
+    description:
+      - The TCP port to listen to.
+    type: int
+    default: 5000
+  data_alerts_path:
+    description:
+      - The json path to find alert data.
+      - Use empty string "" to treat the whole payload data as one alert.
+    type: str
+    default: "alerts"
+  data_host_path:
+    description:
+      - The json path inside the alert data to find alerting host.
+      - Use empty string "" if there is no need to find host.
+    type: str
+    default: "labels.instance"
+  data_path_separator:
+    description:
+      - The separator to interpret data_host_path and data_alerts_path.
+    type: str
+    default: "."
+  skip_original_data:
+    description:
+      - true: put only alert data to the queue
+      - false: put sequentially both the received original data and each parsed alert item to the queue.
+    type: bool
+    default: false
+"""
+
+EXAMPLES = r"""
+- ansible.eda.alertmanager:
+    host: 0.0.0.0
+    port: 8000
+    data_alerts_path: alerts
+    data_host_path: labels.instance
+    data_path_separator: .
+"""
+
+
 routes = web.RouteTableDef()
 
 

extensions/eda/plugins/event_source/aws_cloudtrail.py

@@ -1,36 +1,3 @@
-"""aws_cloudtrail.py.
-
-An ansible-rulebook event source module for getting events from an AWS CloudTrail
-
-Arguments:
----------
-    access_key:    Optional AWS access key ID
-    secret_key:    Optional AWS secret access key
-    session_token: Optional STS session token for use with temporary credentials
-    endpoint_url:  Optional URL to connect to instead of the default AWS endpoints
-    region:        Optional AWS region to use
-    delay_seconds: The number of seconds to wait between polling (default 10sec)
-
-    lookup_attributes:  The optional list of lookup attributes.
-                        lookup attribute are dictionary with an AttributeKey (string),
-                        which specifies an attribute on which to filter the events
-                        returned and an AttributeValue (string) which specifies
-                        a value for the specified AttributeKey
-    event_category:     The optional event category to return. (e.g. 'insight')
-
-Example:
--------
-    - ansible.eda.aws_cloudtrail:
-        region: us-east-1
-        lookup_attributes:
-            - AttributeKey: 'EventSource'
-              AttributeValue: 'ec2.amazonaws.com'
-            - AttributeKey: 'ReadOnly'
-              AttributeValue: 'true'
-        event_category: management
-
-"""
-
 import asyncio
 import json
 from datetime import datetime
@@ -39,6 +6,64 @@
 from aiobotocore.session import get_session
 from botocore.client import BaseClient
 
+DOCUMENTATION = r"""
+---
+short_description: Receive events from an AWS CloudTrail
+description:
+  - An ansible-rulebook event source module for getting events from an AWS CloudTrail.
+  - This supports all the authentication methods supported by boto library:
+    https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
+options:
+  access_key:
+    description:
+      - Optional AWS access key ID.
+    type: str
+  secret_key:
+    description:
+      - Optional AWS secret access key.
+    type: str
+  session_token:
+    description:
+      - Optional STS session token for use with temporary credentials.
+    type: str
+  endpoint_url:
+    description:
+      - Optional URL to connect to instead of the default AWS endpoints.
+    type: str
+  region:
+    description:
+      - Optional AWS region to use.
+    type: str
+  delay_seconds:
+    description:
+      - The number of seconds to wait between polling.
+    type: int
+    default: 10
+  lookup_attributes:
+    description:
+      - The optional list of lookup attributes.
+      - A lookup attribute is a dictionary containing an AttributeKey (string),
+        which specifies the attribute used to filter returned events, and an
+        AttributeValue (string), which defines the value for the specified AttributeKey.
+    type: list
+    elements: str
+  event_category:
+    description:
+      - The optional event category to return. (e.g. 'insight')
+    type: str
+"""
+
+EXAMPLES = r"""
+- ansible.eda.aws_cloudtrail:
+    region: us-east-1
+    lookup_attributes:
+      - AttributeKey: 'EventSource'
+        AttributeValue: 'ec2.amazonaws.com'
+      - AttributeKey: 'ReadOnly'
+        AttributeValue: 'true'
+    event_category: management
+"""
+
 
 def _cloudtrail_event_to_dict(event: dict[str, Any]) -> dict[str, Any]:
     event["EventTime"] = event["EventTime"].isoformat()

extensions/eda/plugins/event_source/aws_sqs_queue.py

@@ -1,26 +1,3 @@
-"""aws_sqs_queue.py.
-
-An ansible-rulebook event source plugin for receiving events via an AWS SQS queue.
-
-Arguments:
----------
-    access_key:    Optional AWS access key ID
-    secret_key:    Optional AWS secret access key
-    session_token: Optional STS session token for use with temporary credentials
-    endpoint_url:  Optional URL to connect to instead of the default AWS endpoints
-    region:        Optional AWS region to use
-    name:          Name of the queue
-    delay_seconds: The SQS long polling duration. Set to 0 to disable. Defaults to 2.
-
-Example:
--------
-    - ansible.eda.aws_sqs_queue:
-        region: us-east-1
-        name: eda
-        delay_seconds: 10
-
-"""
-
 import asyncio
 import json
 import logging
@@ -29,6 +6,54 @@
 import botocore.exceptions
 from aiobotocore.session import get_session
 
+DOCUMENTATION = r"""
+---
+short_description: Receive events via an AWS SQS queue.
+description:
+  - An ansible-rulebook event source plugin for receiving events via an AWS SQS queue.
+  - This supports all the authentication methods supported by boto library:
+    https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
+options:
+  access_key:
+    description:
+      - Optional AWS access key ID.
+    type: str
+  secret_key:
+    description:
+      - Optional AWS secret access key.
+    type: str
+  session_token:
+    description:
+      - Optional STS session token for use with temporary credentials.
+    type: str
+  endpoint_url:
+    description:
+      - Optional URL to connect to instead of the default AWS endpoints.
+    type: str
+  region:
+    description:
+      - Optional AWS region to use.
+    type: str
+  name:
+    description:
+      - Name of the queue.
+    type: str
+    required: true
+  delay_seconds:
+    description:
+      - The SQS long polling duration.
+      - Set to 0 to disable.
+    type: int
+    default: 2
+"""
+
+EXAMPLES = r"""
+- ansible.eda.aws_sqs_queue:
+    region: us-east-1
+    name: eda
+    delay_seconds: 10
+"""
+
 
 # pylint: disable=too-many-locals
 async def main(queue: asyncio.Queue[Any], args: dict[str, Any]) -> None: