Merge pull request #3899 from luixxiul/fix

Edit docs for bots: adopt the common format

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`.
 

docs/configuring-playbook-bot-mjolnir.md

@@ -20,7 +20,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir
 
 If you would like Mjolnir to be able to deactivate users, move aliases, shutdown rooms, 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).
 
@@ -60,7 +60,7 @@ Finally invite the `@bot.mjolnir:example.com` account you created earlier into t
 
 ## 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 Mjolnir
@@ -109,7 +109,7 @@ matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_u
 
 When NOT using Pantalaimon, Mjolnir 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_mjolnir_access_token: "ACCESS_TOKEN_HERE"

docs/configuring-playbook-email2matrix.md

@@ -38,7 +38,7 @@ Inviting additional people to the room is okay too.
 
 Take note of each room's room ID (different clients show the room ID in a different place). You'll need the room ID when [configuring the playbook](#adjusting-the-playbook-configuration) below.
 
-### Obtaining an access token for the sender user
+### Obtain an access token for the sender user
 
 In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 

docs/howto-server-delegation.md

@@ -51,7 +51,7 @@ To use DNS SRV record validation, you need to:
 
 For more details on how to configure the playbook to work with SRV delegation, take a look at this documentation: [Server Delegation via a DNS SRV record (advanced)](howto-srv-server-delegation.md)
 
-### Obtaining certificates
+### Obtain certificates
 
 How you can obtain a valid certificate for `example.com` on the `matrix.example.com` server is up to you.