docs: 📝 add documentation

.github/workflows/docs.yml

@@ -0,0 +1,73 @@
+name: documentation
+on:
+  push:
+    branches:
+      - main
+
+env:
+  PYTHON_VERSION: 3.x
+
+permissions:
+  contents: write
+  id-token: write
+  pages: write
+
+jobs:
+  documentation:
+    name: Build documentation
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python runtime
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: Set up build cache
+        uses: actions/cache/restore@v3
+        with:
+          key: ekizu-${{ hashfiles('.cache/**') }}
+          path: .cache
+          restore-keys: |
+            ekizu-
+
+      - name: Install Doxide
+        run: |
+          echo 'deb http://download.indii.org/deb jammy main' | sudo tee /etc/apt/sources.list.d/indii.org.list
+          curl -fsSL https://download.indii.org/deb/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/indii.org.gpg > /dev/null
+          sudo apt-get update && sudo apt-get install doxide
+
+      - name: Install Python dependencies
+        run: pip install mkdocs mkdocs-material
+
+      - name: Build documentation
+        run: |
+          mkdocs build --clean
+          mkdocs --version
+        working-directory: docs
+
+      - name: Adjust permissions
+        run: |
+          chmod -c -R +rX site/ | while read line; do
+            echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+        working-directory: docs
+
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/site
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4
+
+      - name: Save build cache
+        uses: actions/cache/save@v3
+        with:
+          key: ekizu-${{ hashfiles('.cache/**') }}
+          path: .cache

.gitignore

@@ -1,5 +1,6 @@
 [Bb]uild/*
-[Dd]ocs/*
+docs/docs/api
+docs/site
 CMakeCache.*
 CMakeFiles/*
 [Tt]esting/*

docs/README.md

@@ -0,0 +1,21 @@
+# Build Documentation
+
+This subdirectory is used to build the documentation.
+
+## Dependencies
+
+- [doxide](https://github.com/lawmurray/doxide)
+- [mkdocs](https://github.com/mkdocs/mkdocs)
+
+To build the documentation, run:
+
+```bash
+doxide build
+mkdocs build
+```
+
+To serve the documentation locally, run:
+
+```bash
+mkdocs serve
+```

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

@@ -0,0 +1,76 @@
+# Creating a Discord Bot
+
+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) {
+ const std::string token{std::getenv("DISCORD_TOKEN")};
+ HttpClient http{token};
+ Shard shard{ShardId::ONE, token, Intents::AllIntents};
+
+ while (true) {
+  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;
+  }
+
+  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) {
+   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();
+}
+```
+
+Congratulations, you've successfully set up a bot!
+
+To see what else you can do with this library, see [examples](https://github.com/jontitorr/ekizu/tree/main/examples).

docs/docs/getting-started.md

@@ -0,0 +1,23 @@
+# Getting Started
+
+## Installation
+
+To install from source, clone the Ekizu repo with:
+
+```bash
+git clone https://github.com/jontitorr/ekizu
+```
+
+Build and install with:
+
+```bash
+cd ekizu
+cmake -S. -Bbuild
+cmake --build build --target install
+```
+
+The last command may need sudo. Alternatively, provide a prefix to install somewhere local:
+
+```bash
+cmake --build build --target install --prefix $HOME/.local
+```

docs/docs/index.md

@@ -0,0 +1,3 @@
+---
+template: home.html
+---

docs/doxide.yaml

@@ -0,0 +1,7 @@
+title: ekizu
+description:
+output: docs/api
+files:
+  - "../include/ekizu/**/*.hpp"
+defines:
+  EKIZU_EXPORT: ""

docs/material/overrides/home.html

@@ -0,0 +1,23 @@
+{% extends "main.html" %}
+{% block tabs %}
+  {{ super() }}
+  <style>.md-header{position:initial}.md-main__inner{margin:0}.md-content{display:none}@media screen and (min-width:60em){.md-sidebar--secondary{display:none}}@media screen and (min-width:76.25em){.md-sidebar--primary{display:none}}</style>
+  <section class="mdx-container">
+    <div class="md-grid md-typeset">
+      <div class="mdx-hero">
+        <div class="mdx-hero__image">
+          <img src="assets/images/illustration.png" alt="" width="1659" height="1200" draggable="false">
+        </div>
+        <div class="mdx-hero__content">
+          <h1>Write performant, cross-platform Discord bots</h1>
+          <p>Install it with just a few steps.</p>
+          <a href="{{ 'getting-started/' | url }}" title="Get Started" class="md-button md-button--primary">
+            Get Started
+          </a>
+        </div>
+      </div>
+    </div>
+  </section>
+{% endblock %}
+{% block content %}{% endblock %}
+{% block footer %}{% endblock %}