From 61aaca3924e8bf109004a5efd61dfbe116072ac2 Mon Sep 17 00:00:00 2001
From: jeanluc <lkubb@protonmail.com>
Date: Sat, 5 Oct 2024 00:21:54 +0200
Subject: [PATCH] Improve docs a bit

---
 docs/index.rst                                |  1 +
 docs/topics/configuration.md                  | 22 ++++++++++++++++
 .../telegram/beacons/telegram_bot_msg.py      | 26 +++++++++++--------
 src/saltext/telegram/modules/telegram.py      | 14 +++-------
 .../telegram/returners/telegram_return.py     | 20 +++-----------
 5 files changed, 44 insertions(+), 39 deletions(-)
 create mode 100644 docs/topics/configuration.md

diff --git a/docs/index.rst b/docs/index.rst
index 40e7166..6726771 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,6 +9,7 @@ Salt Extension for interacting with Telegram
   :hidden:
 
   topics/installation
+  topics/configuration
 
 .. toctree::
   :maxdepth: 2
diff --git a/docs/topics/configuration.md b/docs/topics/configuration.md
new file mode 100644
index 0000000..172592e
--- /dev/null
+++ b/docs/topics/configuration.md
@@ -0,0 +1,22 @@
+# Configuration
+## General
+In order to send a message via Telegram, you need to provide a `chat_id` and a `token`.
+If you don't pass them as parameters when calling functions from the execution module,
+they need to be defined inside the minion configuration or the pillar.
+These configuration values can be specified in either of the following ways:
+
+```yaml
+telegram:
+  chat_id: '123456789'
+  token: '00000000:xxxxxxxxxxxxxxxxxxxxxxxx'
+```
+
+```yaml
+telegram.chat_id: '123456789'
+telegram.token: '00000000:xxxxxxxxxxxxxxxxxxxxxxxx'
+```
+
+## Returner
+
+Using the returner module requires the above configuration values
+to be set in either the minion configuration or the pillar.
diff --git a/src/saltext/telegram/beacons/telegram_bot_msg.py b/src/saltext/telegram/beacons/telegram_bot_msg.py
index ae097f7..df07e6c 100644
--- a/src/saltext/telegram/beacons/telegram_bot_msg.py
+++ b/src/saltext/telegram/beacons/telegram_bot_msg.py
@@ -1,5 +1,19 @@
 """
-Beacon to emit Telegram messages
+Beacon to emit Telegram messages.
+
+Configuration example
+---------------------
+
+Include the following in the minion configuration:
+
+.. code-block:: yaml
+
+    beacons:
+      telegram_bot_msg:
+        - token: "<bot access token>"
+        - accept_from:
+          - "<valid username>"
+        - interval: 10
 """
 
 import logging
@@ -56,16 +70,6 @@ def beacon(config):
     """
     Emit a dict with a key "msgs" whose value is a list of messages
     sent to the configured bot by one of the allowed usernames.
-
-    .. code-block:: yaml
-
-        beacons:
-          telegram_bot_msg:
-            - token: "<bot access token>"
-            - accept_from:
-              - "<valid username>"
-            - interval: 10
-
     """
 
     config = salt.utils.beacons.list_to_dict(config)
diff --git a/src/saltext/telegram/modules/telegram.py b/src/saltext/telegram/modules/telegram.py
index 42c40c8..6af7405 100644
--- a/src/saltext/telegram/modules/telegram.py
+++ b/src/saltext/telegram/modules/telegram.py
@@ -1,13 +1,5 @@
 """
 Module for sending messages via Telegram.
-
-:configuration: In order to send a message via the Telegram, certain
-    configuration is required in /etc/salt/minion on the relevant minions or
-    in the pillar. Some sample configs might look like::
-
-        telegram.chat_id: '123456789'
-        telegram.token: '00000000:xxxxxxxxxxxxxxxxxxxxxxxx'
-
 """
 
 import logging
@@ -34,7 +26,7 @@ def __virtual__():
 
 def _get_chat_id():
     """
-    Retrieves and return the Telegram's configured chat id
+    Retrieve and return the Telegram's configured chat id
 
     :return:    String: the chat id string
     """
@@ -49,7 +41,7 @@ def _get_chat_id():
 
 def _get_token():
     """
-    Retrieves and return the Telegram's configured token
+    Retrieve and return the Telegram's configured token
 
     :return:    String: the token string
     """
@@ -93,7 +85,7 @@ def _post_message(message, chat_id, token):
     Send a message to a Telegram chat.
 
     :param chat_id:     The chat id.
-    :param message:     The message to send to the telegram chat.
+    :param message:     The message to send to the Telegram chat.
     :param token:       The Telegram API token.
     :return:            Boolean if message was sent successfully.
     """
diff --git a/src/saltext/telegram/returners/telegram_return.py b/src/saltext/telegram/returners/telegram_return.py
index ec1c2fc..e739de3 100644
--- a/src/saltext/telegram/returners/telegram_return.py
+++ b/src/saltext/telegram/returners/telegram_return.py
@@ -1,25 +1,11 @@
 """
-Return salt data via Telegram.
+Return Salt data via Telegram.
 
-The following fields can be set in the minion conf file::
-
-    telegram.chat_id (required)
-    telegram.token (required)
-
-Telegram settings may also be configured as:
-
-.. code-block:: yaml
-
-    telegram:
-      chat_id: 000000000
-      token: 000000000:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-
-To use the Telegram return, append '--return telegram' to the salt command.
+To use the Telegram returner, append ``--return telegram`` to the Salt command.
 
 .. code-block:: bash
 
     salt '*' test.ping --return telegram
-
 """
 
 import logging
@@ -37,7 +23,7 @@ def _get_options(ret=None):
 
     :param ret:     The data to be sent.
     :return:        Dictionary containing the data and options needed to send
-                    them to telegram.
+                    a message to Telegram.
     """
     attrs = {"chat_id": "chat_id", "token": "token"}