Edit docs for bots: adopt the common format

- Add "To use the bot" if it does not exist: adopt the format of the docs for bridges
- Add "Prerequisites" section if an API key or user account is required
- Use the common instruction for getting an access token
- Replace "Get" with "Obtain" about getting keys or access tokens
- Replace placeholders for access tokens on docs/configuring-playbook-bot-go.neb.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

Author: Suguru Hirahara

docs/configuring-playbook-alertmanager-receiver.md

@@ -22,7 +22,7 @@ You can use the playbook to [register a new user](registering-users.md):
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.alertmanager.receiver password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
-### Get an access token
+### Obtain an access token
 
 The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
@@ -36,15 +36,14 @@ Then, log in as the bot using any Matrix client of your choosing, accept the roo
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#get-an-access-token).
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
 
 ```yaml
 matrix_alertmanager_receiver_enabled: true
 
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_alertmanager_receiver_config_matrix_user_id_localpart: "bot.alertmanager.receiver"
 
-# Specify the bot user's access token here.
 matrix_alertmanager_receiver_config_matrix_access_token: "ACCESS_TOKEN_HERE"
 
 # Optionally, configure some mappings (URL-friendly room name -> actual Matrix room ID).

docs/configuring-playbook-bot-baibot.md

@@ -30,7 +30,7 @@ Depending on your current `vars.yml` file and desired configuration, **you may r
 
 ### Base configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_baibot_enabled: true

docs/configuring-playbook-bot-buscarron.md

@@ -6,7 +6,7 @@ Buscarron is bot that receives HTTP POST submissions of web forms and forwards t
 
 ## Adjusting the playbook configuration
 
-To enable Buscarron, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_buscarron_enabled: true

docs/configuring-playbook-bot-chatgpt.md

@@ -6,11 +6,15 @@ The playbook can install and configure [matrix-chatgpt-bot](https://github.com/m
 
 Talk to [ChatGPT](https://openai.com/blog/chatgpt/) via your favourite Matrix client!
 
-## Register the bot account
+## Prerequisites
 
-The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
+### Obtain an OpenAI API key
 
-You **need to register the bot user manually** before setting up the bot.
+To use the bot, you'd need to obtain an API key from [https://platform.openai.com/account/api-keys](https://platform.openai.com/account/api-keys).
+
+### Register the bot account
+
+The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
 
 Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
 
@@ -20,37 +24,31 @@ You can use the playbook to [register a new user](registering-users.md):
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
-## Get an access token and create encryption keys
+### Obtain an access token and create encryption keys
 
-Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
 To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [Element documentation](https://element.io/help#encryption6).
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `API_KEY_HERE` with the API key retrieved [here](#obtain-an-openai-api-key) and `ACCESS_TOKEN_HERE` with the access token created [here](#obtain-an-access-token-and-create-encryption-keys), respectively.
 
 ```yaml
 matrix_bot_chatgpt_enabled: true
 
-# Obtain a new API key from https://platform.openai.com/account/api-keys
-matrix_bot_chatgpt_openai_api_key: ''
+matrix_bot_chatgpt_openai_api_key: 'API_KEY_HERE'
 
-# This is the default username
+# Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_bot_chatgpt_matrix_bot_username_localpart: 'bot.chatgpt'
 
-# Matrix access token (from bot user above)
-# see: https://webapps.stackexchange.com/questions/131056/how-to-get-an-access-token-for-element-riot-matrix
-matrix_bot_chatgpt_matrix_access_token: ''
+matrix_bot_chatgpt_matrix_access_token: 'ACCESS_TOKEN_HERE'
 
 # Configuring the system promt used, needed if the bot is used for special tasks.
 # More information: https://github.com/mustvlad/ChatGPT-System-Prompts
 matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a large language model trained by OpenAI.'
-
 ```
 
-You will need to get tokens for ChatGPT.
-
 ## Installing
 
 After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:

docs/configuring-playbook-bot-draupnir.md

@@ -24,7 +24,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupni
 
 If you would like Draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports (see [below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
 
-### Get an access token
+### Obtain an access token
 
 The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
@@ -64,7 +64,7 @@ Finally invite the `@bot.draupnir:example.com` account you created earlier into
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`.
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`.
 
 ```yaml
 # Enable Draupnir
@@ -113,7 +113,7 @@ matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_
 
 When NOT using Pantalaimon, Draupnir does not log in by itself and you must give it an access token for its bot account.
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#get-an-access-token).
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
 
 ```yaml
 matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE"

docs/configuring-playbook-bot-go-neb.md

@@ -8,11 +8,11 @@ Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the ori
 
 See the project's [documentation](https://github.com/matrix-org/go-neb/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-## Registering the bot account
+## Prerequisites
 
-The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
+### Register the bot account
 
-You **need to register the bot user manually** before setting up the bot.
+The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
 
 Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
 
@@ -22,11 +22,13 @@ You can use the playbook to [register a new user](registering-users.md):
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
-Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
+### Obtain an access token
+
+The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
 ## Adjusting the playbook configuration
 
-To enable Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_GONEB_HERE` and `ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE` with the ones created [above](#obtain-an-access-token).
 
 ```yaml
 matrix_bot_go_neb_enabled: true
@@ -35,7 +37,7 @@ matrix_bot_go_neb_enabled: true
 # Use the access token you obtained in the step above.
 matrix_bot_go_neb_clients:
   - UserID: "@goneb:{{ matrix_domain }}"
-    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+    AccessToken: "ACCESS_TOKEN_FOR_GONEB_HERE"
     DeviceID: "DEVICE1"
     HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
     Sync: true
@@ -44,7 +46,7 @@ matrix_bot_go_neb_clients:
     AcceptVerificationFromUsers: [":{{ matrix_domain }}"]
 
   - UserID: "@another_goneb:{{ matrix_domain }}"
-    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+    AccessToken: "ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE"
     DeviceID: "DEVICE2"
     HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
     Sync: false
@@ -105,7 +107,7 @@ matrix_bot_go_neb_services:
       api_key: "AIzaSyA4FD39m9"
       cx: "AIASDFWSRRtrtr"
 
-# Get a key via https://api.imgur.com/oauth2/addclient
+# Obtain a key via https://api.imgur.com/oauth2/addclient
 # Select "oauth2 without callback url"
   - ID: "imgur_service"
     Type: "imgur"

docs/configuring-playbook-bot-honoroit.md

@@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/etkecc/honoroit/blob/main/R
 
 ## Adjusting the playbook configuration
 
-To enable Honoroit, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_honoroit_enabled: true

docs/configuring-playbook-bot-matrix-registration-bot.md

@@ -6,7 +6,7 @@ The bot allows you to easily **create and manage registration tokens** aka. invi
 
 See the project's [documentation](https://github.com/moan0s/matrix-registration-bot/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-## Configuration
+## Adjusting the playbook configuration
 
 To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 

docs/configuring-playbook-bot-matrix-reminder-bot.md

@@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/anoadragon453/matrix-remind
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_matrix_reminder_bot_enabled: true

docs/configuring-playbook-bot-maubot.md

@@ -8,7 +8,7 @@ See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) t
 
 ## Adjusting the playbook configuration
 
-To enable maubot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_maubot_enabled: true
@@ -75,7 +75,7 @@ You should start in the following order
 2. **Upload some Plugins**: Plugins can be obtained from [here](https://github.com/maubot/maubot#plugins) or any other source.
 3. **Create an instance**: An instance is the actual bot. You have to specify a client which the bot instance will use and the plugin (how the bot will behave)
 
-## Obtaining an access token
+## Obtain an access token
 
 This can be done via `mbc login` then `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)). To run these commands, you'll first need to `exec` into the maubot container with `docker exec -it matrix-bot-maubot sh`.