feat: [AAP-38755] add documentation for pg_listener, range, tick, url_check and webhook plugins

.config/dictionary.txt

@@ -31,6 +31,7 @@ conftest
 conninfo
 containerd
 darglint
+dbname
 deadsnakes
 digestmod
 docsite
@@ -46,6 +47,7 @@ jainnikhil
 keygen
 keypass
 keytool
+libpq
 libsystemd
 mydb
 myqueue

extensions/eda/plugins/event_source/pg_listener.py

@@ -1,60 +1,3 @@
-"""pg_listener.py.
-
-An ansible-rulebook event source plugin for reading events from
-pg_pub_sub
-
-Arguments:
-# cSpell:ignore libpq
----------
-    dsn: Optional, the connection string/dsn for Postgres as supported by psycopg/libpq
-        refer to https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-KEYWORD-VALUE
-        Either dsn or postgres_params is required
-    postgres_params: Optional, dict, the parameters for the pg connection as they are supported by psycopg/libpq
-        refer to https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
-        If the param is already in the dsn, it will be overridden by the value in postgres_params
-        Either dsn or postgres_params is required
-    channels: Required, the list of channels to listen
-
-Examples:
--------
-    - ansible.eda.pg_listener:
-        dsn: "host=localhost port=5432 dbname=mydb"
-        channels:
-          - my_events
-          - my_alerts
-
-    - ansible.eda.pg_listener:
-        postgres_params:
-          host: localhost
-          port: 5432
-          dbname: mydb
-        channels:
-          - my_events
-          - my_alerts
-
-Chunking:
----------
-   This is just informational a user doesn't have to do anything
-   special to enable chunking. The sender which is the pg_notify
-   action from ansible rulebook will decide if chunking needs to
-   happen based on the size of the payload.
-   If the messages are over 7KB the sender will chunk the messages
-   into separate payloads with each payload having having the following
-   keys
-   * _message_chunked_uuid   The unique message uuid
-   * _message_chunk_count    The number of chunks for the message
-   * _message_chunk_sequence The sequence of the current chunk
-   * _chunk                  The actual chunk
-   * _message_length         The total length of the message
-   * _message_xx_hash        A hash for the entire message
-
-   The pg_listener source will assemble the chunks and once all the
-   chunks have been received it will deliver the entire payload to the
-   rulebook engine. Before the payload is delivered we validated that the entire
-   message has been received by validate its computed hash.
-
-"""
-
 import asyncio
 import json
 import logging
@@ -63,6 +6,68 @@
 import xxhash
 from psycopg import AsyncConnection, OperationalError
 
+DOCUMENTATION = r"""
+---
+short_description: Read events from pg_pub_sub.
+description:
+  - An ansible-rulebook event source plugin for reading events from pg_pub_sub.
+options:
+  dsn:
+    description:
+      - The connection string/dsn for Postgres as supported by psycopg/libpq.
+        Refer to https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-KEYWORD-VALUE.
+        Either dsn or postgres_params is required.
+    type: str
+  postgres_params:
+    description:
+      - The parameters for the pg connection as they are supported by psycopg/libpq.
+        Refer to https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
+        If the param is already in the dsn, it will be overridden by the value in postgres_params.
+        Either dsn or postgres_params is required.
+    type: dict
+  channels:
+    description:
+      - The list of channels to listen
+    type: list
+    elements: str
+    required: true
+notes:
+  - Chunking - this is just informational, a user doesn't have to do anything
+    special to enable chunking. The sender, which is the pg_notify
+    action from ansible-rulebook, will decide if chunking needs to
+    happen based on the size of the payload.
+  - If the messages are over 7KB the sender will chunk the messages
+    into separate payloads with each payload having the following
+    keys:
+    * _message_chunked_uuid   The unique message uuid
+    * _message_chunk_count    The number of chunks for the message
+    * _message_chunk_sequence The sequence of the current chunk
+    * _chunk                  The actual chunk
+    * _message_length         The total length of the message
+    * _message_xx_hash        A hash for the entire message
+  - The pg_listener source will assemble the chunks and once all the
+    chunks have been received it will deliver the entire payload to the
+    rulebook engine. Before the payload is delivered we validated that the entire
+    message has been received by validating its computed hash.
+"""
+
+EXAMPLES = r"""
+- ansible.eda.pg_listener:
+    dsn: "host=localhost port=5432 dbname=mydb"
+    channels:
+      - my_events
+      - my_alerts
+
+- ansible.eda.pg_listener:
+    postgres_params:
+      host: localhost
+      port: 5432
+      dbname: mydb
+    channels:
+      - my_events
+      - my_alerts
+"""
+
 LOGGER = logging.getLogger(__name__)
 
 MESSAGE_CHUNKED_UUID = "_message_chunked_uuid"

extensions/eda/plugins/event_source/range.py

@@ -1,21 +1,23 @@
-"""range.py.
-
-An ansible-rulebook event source plugin for generating events with an
-increasing index i.
-
-Arguments:
----------
-    limit: The upper limit of the range of the index.
-
-Example:
--------
-    - ansible.eda.range:
-        limit: 5
+import asyncio
+from typing import Any
 
+DOCUMENTATION = r"""
+---
+short_description: Generate events with an increasing index i.
+description:
+  - An ansible-rulebook event source plugin for generating events with an increasing index i.
+options:
+  limit:
+    description:
+      - The upper limit of the range of the index.
+    type: int
+    default: 0
 """
 
-import asyncio
-from typing import Any
+EXAMPLES = r"""
+- ansible.eda.range:
+    limit: 5
+"""
 
 
 async def main(queue: asyncio.Queue[Any], args: dict[str, Any]) -> None:

extensions/eda/plugins/event_source/tick.py

@@ -1,23 +1,25 @@
-"""tick.py.
-
-An ansible-rulebook event source plugin for generating events with an increasing index
-i that never ends.
-
-Arguments:
----------
-    delay: time between ticks
-
-Example:
--------
-    - ansible.eda.tick:
-        delay: 5
-
-"""
-
 import asyncio
 import itertools
 from typing import Any
 
+DOCUMENTATION = r"""
+---
+short_description: Generate events with an increasing index i that never ends.
+description:
+  - An ansible-rulebook event source plugin for generating events with an increasing index i that never ends.
+options:
+  delay:
+    description:
+      - The delay (in seconds) between ticks.
+    type: int
+    default: 1
+"""
+
+EXAMPLES = r"""
+- ansible.eda.tick:
+    delay: 5
+"""
+
 
 async def main(queue: asyncio.Queue[Any], args: dict[str, Any]) -> None:
     """Generate events with an increasing index i and a time between ticks."""

extensions/eda/plugins/event_source/url_check.py

@@ -1,29 +1,39 @@
-"""url_check.py.
-
-An ansible-rulebook event source plugin that polls a set of URLs and sends
-events with their status.
-
-Arguments:
----------
-    urls - a list of urls to poll
-    delay - the number of seconds to wait between polling
-    verify_ssl - verify SSL certificate
-
-Example:
--------
-    - name: check web server
-      ansible.eda.url_check:
-        urls:
-          - http://44.201.5.56:8000/docs
-        delay: 10
-
-"""
-
 import asyncio
 from typing import Any
 
 import aiohttp
 
+DOCUMENTATION = r"""
+---
+short_description: Poll a set of URLs and sends events with their status.
+description:
+  - An ansible-rulebook event source plugin that polls a set of URLs and sends events with their status.
+options:
+  urls:
+    description:
+      - A list of urls to poll.
+    type: list
+    elements: str
+    required: true
+  delay:
+    description:
+      - The delay (in seconds) between polling.
+    type: int
+    default: 1
+  verify_ssl:
+    description:
+      - Verify SSL certificate.
+    type: bool
+    default: true
+"""
+
+EXAMPLES = r"""
+- ansible.eda.url_check:
+    urls:
+      - http://44.201.5.56:8000/docs
+    delay: 10
+"""
+
 OK = 200