docs: 📝 add discord bot guide

docs/docs/building-a-discord-bot.md

@@ -0,0 +1,140 @@
+# Building a Discord Bot
+
+## Prerequisites
+
+You will need to have the following things installed:
+
+- [CMake](https://cmake.org/download/) (version >= 3.16)
+- Compiler with C++17 support, i.e. MSVC, GCC, Clang
+- [Git](https://git-scm.com/)
+- [ekizu](https://github.com/jontitorr/ekizu) (see [Installation](getting-started.md))
+
+## Create a CMake project
+
+In an empty directory, create the following files and directories:
+
+- `CMakeLists.txt`
+- `main.cpp`
+
+You'll need to modify the `CMakeLists.txt` to tell CMake what it's looking for, and other information.
+Here is an example CMake configuration, you can adapt it according to your needs:
+
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(discord-bot VERSION 0.1.0)
+
+# Create an executable
+add_executable(discord-bot main.cpp)
+
+# Find ekizu
+find_package(ekizu REQUIRED)
+
+# Link to the ekizu library
+target_link_libraries(discord-bot ekizu::ekizu)
+```
+
+## The program
+
+Ekizu makes use of the [asio](https://github.com/chriskohlhoff/asio) library for
+its asynchronous I/O. This allows us to achieve concurrency similar to other languages like JavaScript. For an easy wrapper around the interface, we take advantage of the `async_main` macro which wraps what would be your main function in a coroutine.
+
+It is recommended to learn more about how asio works and to have a some [examples](https://github.com/chriskohlhoff/asio/tree/master/asio/src/examples) for more clarification.
+
+Below is an example of a simple bot, utilizing the `async_main` macro.
+
+```cpp
+#include <ekizu/async_main.hpp>
+#include <ekizu/http_client.hpp>
+#include <ekizu/shard.hpp>
+
+using namespace ekizu;
+
+Result<> handle_event(
+    const Event& ev, const HttpClient& http, const asio::yield_context& yield);
+
+// Runs main in a coroutine, similar to Rust's #[tokio::main].
+async_main(const asio::yield_context& yield)
+{
+    // Place your token here.
+    const std::string token { "YOUR_DISCORD_TOKEN_HERE" };
+    HttpClient http { token };
+    Shard shard { ShardId::ONE, token, Intents::AllIntents };
+
+    while (true) {
+        // Wait for the next gateway event.
+        auto res = shard.next_event(yield);
+
+        if (!res) {
+            if (res.error().failed()) {
+                fmt::println(
+                    "Failed to get next event: {}", res.error().message());
+                return res.error();
+            }
+            // Could be handling a non-dispatch event.
+            continue;
+        }
+
+        // Run this event in a coroutine.
+        asio::spawn(
+            yield,
+            [e = std::move(res.value()), &http](
+                auto y) { (void)handle_event(e, http, y); },
+            asio::detached);
+    }
+
+    return outcome::success();
+}
+
+Result<> handle_event(
+    const Event& ev, const HttpClient& http, const asio::yield_context& yield)
+{
+    std::visit(
+        [&](auto&& event) mutable {
+            using T = std::decay_t<decltype(event)>;
+
+            // Catch the `MessageCreate` event, which contains our message.
+            if constexpr (std::is_same_v<T, MessageCreate>) {
+                const auto& [msg] = event;
+
+                // If the message is "ping", respond with "pong".
+                if (msg.content == "ping") {
+                    (void)http.create_message(msg.channel_id)
+                        .content("pong")
+                        .send(yield);
+                }
+            }
+        },
+        ev);
+
+    return outcome::success();
+}
+```
+
+For more feature-complete examples, see [examples](https://github.com/jontitorr/ekizu/tree/main/examples).
+
+## Build the bot
+
+For this process we need to do two things:
+
+1. Configure CMake
+
+    ```bash
+    cmake -S. -Bbuild
+    ```
+
+2. Build the bot
+
+    ```bash
+    cmake --build build # add -j <# of cores> if you would like to use more cores when building
+    ```
+
+After that has finished, you can call:
+
+```bash
+build/discord-bot
+```
+
+???+ note
+    The path of the executable will differ based on your configuration environment.
+
+If everything went well, you should see your bot come online!

docs/docs/creating-a-bot-token.md

@@ -0,0 +1,54 @@
+# Creating a Discord Bot Token
+
+## Getting your Discord token
+
+Before you start coding, you need to create and register your bot in the Discord developer portal. You can then add this bot to your Discord server.
+
+To create a bot:
+
+1. Make sure you’re logged on to the [Discord website](https://discord.com/).
+2. Navigate to the [application page](https://discord.com/developers/applications)
+3. Click on the “New Application” button.
+
+    ![The new application button.](assets/images/discord_create_app_button.webp)
+
+4. Give the application a name and click “Create”.
+
+    ![The new application form filled in.](assets/images/discord_create_app_form.webp)
+
+5. Navigate to the “Bot” tab to configure it.
+6. Make sure that Public Bot is ticked if you want others to invite your bot.
+    - You should also make sure that `Require OAuth2 Code Grant` is unchecked unless you are developing a service that needs it. If you’re unsure, then leave it unchecked.
+
+     ![How the Bot User options should look like for most people.](assets/images/discord_bot_user_options.webp)
+
+7. Copy the token using the “Copy” button.
+
+    ???+ warning
+        It should be worth noting that this token is essentially your bot’s password. You should never share this with someone else. In doing so, someone can log in to your bot and do malicious things, such as leaving servers, banning all members inside a server, or pinging everyone maliciously.
+
+        The possibilities are endless, so do not share this token.
+
+        If you accidentally leaked your token, click the “Regenerate” button as soon as possible. This revokes your old token and re-generates a new one. Now you need to use the new token to log in.
+
+And that’s it. You now have a bot account and you can log in with that token.
+
+## Adding the Bot to Your Server
+
+So you’ve made a Bot User but it’s not actually in any server.
+
+If you want to invite your bot you must create an invite URL for it.
+
+1. Make sure you've [created your token](#getting-your-discord-token).
+2. Navigate to the [application page](https://discord.com/developers/applications).
+3. Click on your bot’s page.
+4. Go to the “OAuth2 > URL Generator” tab.
+
+    ![How the OAuth2 page should look like.](assets/images/discord_oauth2.webp)
+
+5. Tick the `bot` checkbox under “scopes”. If your bot uses slash commands, also select `applications.commands`. You can read more about scopes and which you need for your application [here](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes).
+6. Choose the permissions required for your bot to function in the "Bot Permissions" section.
+7. Copy and paste the resulting URL in your browser. Choose a server to invite the bot to, and click "Authorize".
+
+???+ note
+    Bot owners must have 2FA enabled for certain actions and permissions when added to servers that have Server-Wide 2FA enabled. Check the 2FA support page for more information.

docs/mkdocs.yaml

@@ -87,5 +87,7 @@ nav:
   - Home: index.md
   - Getting started:
       - Installation: getting-started.md
-      - Creating a Discord Bot: creating-a-discord-bot.md
+      - Creating a Discord Bot:
+          - Creating a Bot Token: creating-a-bot-token.md
+          - Building a Bot: building-a-discord-bot.md
   - API Reference: api/ekizu/index.md