diff --git a/docs/.pages b/docs/.pages index 91c0086d..6935a28c 100644 --- a/docs/.pages +++ b/docs/.pages @@ -4,4 +4,5 @@ nav: - procedures - hardware - services +- webgroup - contact.md diff --git a/docs/index.md b/docs/index.md index f0a23884..5fada4a6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,6 +24,10 @@ This is mostly intended for admins, future admins, webmasters, and everybody els ## Webgroup +## Webgroup + +The [webgroup](webgroup/index.md) is a subgroup of Redbrick consisting of volunteers who work with the webmaster on a number of projects. + ## New Admins So, you want to become an admin. Brave of you. Here's some stuff you should probably read: diff --git a/docs/res/branches.png b/docs/res/branches.png new file mode 100644 index 00000000..859312b9 Binary files /dev/null and b/docs/res/branches.png differ diff --git a/docs/res/contribute.png b/docs/res/contribute.png new file mode 100644 index 00000000..55db6e93 Binary files /dev/null and b/docs/res/contribute.png differ diff --git a/docs/res/pull-request.png b/docs/res/pull-request.png new file mode 100644 index 00000000..e3affac4 Binary files /dev/null and b/docs/res/pull-request.png differ diff --git a/docs/webgroup/blockbot.md b/docs/webgroup/blockbot.md new file mode 100644 index 00000000..19993fd3 --- /dev/null +++ b/docs/webgroup/blockbot.md @@ -0,0 +1,154 @@ +--- +id: blockbot +aliases: + - Blockbot +tags: + - webgroup + - discord +title: Blockbot +--- + +# Blockbot + +Blockbot is a Discord bot, written in Python, that is maintained by the Redbrick Webgroup. This project uses [`hikari`](https://github.com/hikari-py/hikari/), an opinionated microframework, to interface with the Discord API. [`hikari-arc`](https://github.com/hypergonial/hikari-arc) is the command handler and [`hikari-miru`](https://github.com/hypergonial/hikari-miru) is the component handler of choice. + +## File Structure + +All bot files are under `src/`. + +- `bot.py` + - Contains the bot configuration and instantiation (e.g. loading the bot extensions). +- `extensions/` + - Contains extensions (files) that are loaded when the bot is started. Extensions are a way to split bot logic across multiple files, commonly used to group different features. Extensions can contain plugins, command, event listeners and other logic. [Read more](https://arc.hypergonial.com/guides/plugins_extensions/). +- `examples/` + - Contains example extensions with commands, components and more as reference for developers. +- `config.py` + - Configuration secrets and important constants (such as identifiers) are stored here. The secrets are loaded from environment variables, so you can set them in your shell or in a `.env` file. +- `utils.py` + - Utility functions are stored here, that can be reused across the codebase. + +## Installation + +> [!TIP] +> Docker Compose for local development is highly reccommended. This is similar to how it is deployed on Redbrick. + +### Discord Developer Portal + +As a prerequisite, you need to have an application registered on the Discord developer portal. + +1. Create a Discord application [here](https://discord.com/developers/applications/). +2. Go to *"OAuth2 > URL Generator"* on the left sidebar, select the `bot` and `applications.commands` scopes, and then select the bot permissions you need (for development, you can select `Administrator`). +3. Go to the generated URL and invite the application to the desired server. + +#### Bot Token + +1. Open the application on the Discord developer portal. +2. Go to *"Bot"* on the left sidebar, click `Reset Token`. +3. Copy the newly generated token. + +### Source Code + +1. `git clone` and `cd` into the [blockbot repository](https://github.com/redbrick/blockbot). +2. It is generally advised to work in a Python [virtual environment](https://docs.python.org/3/library/venv.html): + + ```sh +python3 -m venv .venv +source .venv/bin/activate + ``` + +3. Rename `.env.sample` to `.env` inside the repo folder and fill in the environment variables with your secrets. e.g.: + + ``` + TOKEN= + ``` + +4. Run `pip install -r requirements.txt` to install the required packages. +5. Start the bot by running `python3 -m src`. + +### Docker + +1. `git clone` and `cd` into this repository. +2. Create a new file called `.env` inside the repo folder and paste your bot token into the file as such: +``` +TOKEN= +``` +3. Build the docker image `docker build --tag "blockbot-testing" .` +4. Run this image `docker run "blockbot-testing"` + +### Docker Compose +1. `git clone` and `cd` into this repository. +2. Create a new file called `.env` inside the repo folder and paste your bot token into the file as such: +``` +TOKEN= +``` +3. Run the docker-compose.yml file `docker-compose up -d` + +## Library Resources + +- [`hikari` Documentation](https://docs.hikari-py.dev/en/latest/) +- [`hikari` Examples](https://github.com/hikari-py/hikari/tree/master/examples) +- [`hikari-arc` Documentation](https://arc.hypergonial.com/) +- [`hikari-arc` Examples](https://github.com/hypergonial/hikari-arc/tree/main/examples/gateway) +- [`hikari-miru` Documentation](https://miru.hypergonial.com/) +- [`hikari-miru` Examples](https://github.com/hypergonial/hikari-miru/tree/main/examples) + +## Usage Guides + +### hikari + +* [Getting Started](https://hg.cursed.solutions/#getting-started) - first steps of using `hikari` +* [Events](https://hg.cursed.solutions/01.events/) - understanding receiving events from Discord with `hikari` + +### hikari-arc + +* [Getting Started](https://arc.hypergonial.com/getting_started/) - first steps of using `hikari-arc` +* [Guides](https://arc.hypergonial.com/guides/) - various guides on aspects of `hikari-arc` + +### hikari-miru + +* [Getting Started](https://miru.hypergonial.com/getting_started/) - first steps of using `hikari-miru` +* [Guides](https://miru.hypergonial.com/guides/) - various guides on aspects of `hikari-miru` + +## What's the difference between `hikari`, `hikari-arc` and `hikari-miru`? + +* `hikari` - the Discord API wrapper. Can be used to, for example: + * [add roles to server members](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.add_role_to_member) + * [create threads](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.create_thread) + * [send individual messages](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.create_message) + * [fetch guild (server) information](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.fetch_guild) + * update member roles ([add role](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.add_role_to_member), [remove role](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.remove_role_from_member), [edit roles](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.edit_member)) + * listen for events from Discord, like [message edits](https://docs.hikari-py.dev/en/stable/reference/hikari/events/message_events/#hikari.events.message_events.MessageUpdateEvent) +* `hikari-arc` - the command handler. Can be used to: + * create application commands ([slash](https://arc.hypergonial.com/guides/options/#declaring-options), [message & user commands](https://arc.hypergonial.com/guides/context_menu/)) + * respond to command interactions +* `hikari-miru` - the component handler. Can be used to: + * create message components (buttons, select menus & modals) + * respond to component interactions (button clicks, select menu selections & modal submissions) + +## Why use a `hikari.GatewayBot` instead of a `hikari.RESTBot`? + +**TL;DR:** `RESTBot`s do not receive events required for some blockbot features (e.g. starboard), so `GatewayBot` must be used instead. + +`GatewayBot`s connect to Discord via a websocket, and Discord sends events (including interactions) through this websocket. `RESTBot`s run a web server which Discord sends only interactions to (not events) via HTTP requests. These events are required for specific blockbot features, like starboard (which uses reaction create/remove events). + +**Further reading:** + +## What's the difference between `hikari.GatewayBot`, `arc.GatewayClient` and `miru.Client`? + +* `hikari.GatewayBot` is the actual Discord bot. It: + * manages the websocket connection to Discord + * sends HTTP requests to the Discord REST API + * caches information received in events sent by Discord +* `arc.GatewayClient` adds additional functionality to `hikari.GatewayBot` for: + * splitting the bot across multiple files using [extensions](https://arc.hypergonial.com/guides/plugins_extensions/#extensions) + * grouping commands using [plugins](https://arc.hypergonial.com/guides/plugins_extensions/#plugins) + * easily creating and managing commands and [command groups](https://arc.hypergonial.com/guides/command_groups/) + * accessing objects globally (in any extension, plugin or command) using [dependency injection](https://arc.hypergonial.com/guides/dependency_injection/) (e.g. a database connection) +* `miru.Client` adds additional functionality to `hikari.GatewayBot` for: + * creating message components using [views](https://miru.hypergonial.com/getting_started/#first-steps) + * creating [modals](https://miru.hypergonial.com/guides/modals/) + * creating [navigators](https://miru.hypergonial.com/guides/navigators/) and [menus](https://miru.hypergonial.com/guides/menus/) using views + +## Do's and Don'ts + +* Always try to get data from the cache before fetching it from the API. diff --git a/docs/webgroup/contributing.md b/docs/webgroup/contributing.md new file mode 100644 index 00000000..4095aad9 --- /dev/null +++ b/docs/webgroup/contributing.md @@ -0,0 +1,57 @@ +--- +id: contributing +aliases: + - Contributing to Webgroup + - contributing +tags: + - webgroup +title: Contributing to Webgroup +--- + +# Contributing to Webgroup + +## Basic Contribution Workflow + +- Fork the repository on GitHub. +- Clone your fork of the repository. + + ```bash + git clone + ``` + +- Switch to a new branch (name it appropriately!) + + ```bash + git checkout -b + ``` + +- Make changes to the codebase. + +> [!NOTE] +> You don't have to make all the necessary changes in one commit. It's much better to split a bigger pull request over multiple commits. This will make it easier to manage and review. + +- Stage and commit the changes. + + ```bash +git add +git commit -m "" + ``` + +> [!NOTE] Tip +> See [Writing Meaningful Commit Messages](https://reflectoring.io/meaningful-commit-messages/) + +- On GitHub, navigate to your fork repository and switch to the branch you created. + + ![Branches on GitHub](../res/branches.png) + +- Use the ":material-source-pull: Contribute" button to open the pull request page. + + ![Contribution modal on GitHub](../res/contribute.png) + +- Fill in the title and description fields, then open a pull request. If you have not finished making all the necessary changes, then open a **draft** pull request instead. + + ![Pull Request page on GitHub](../res/pull-request.png) + + +> [!NOTE] Tip +> For bigger contributions, it's advisable to open a draft pull request when you begin development so other maintainers (e.g. other members of webgroup) can review your changes and provide feedback as you work. diff --git a/docs/webgroup/index.md b/docs/webgroup/index.md new file mode 100644 index 00000000..a6b1c933 --- /dev/null +++ b/docs/webgroup/index.md @@ -0,0 +1,20 @@ +--- +id: webgroup +aliases: + - Webgroup +tags: + - webgroup +title: Webgroup +--- + +# Webgroup + +The webgroup is a subgroup of Redbrick consisting of volunteers who work with the webmaster on a number of projects including but not limited to: [Blockbot](https://github.com/redbrick/blockbot), the [Redbrick website](https://github.com/redbrick/atlas), and various other projects. + +Read more about how the webgroup operates in [open governance](https://redbrick.dcu.ie/open-governance/webgroup/webgroup.html). + +## Webgroup Projects + +### [Blockbot](blockbot.md) + +A Discord bot, written in Python, that is maintained by the Redbrick Webgroup. diff --git a/mkdocs.yml b/mkdocs.yml index 83d14713..6964697b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -84,6 +84,9 @@ markdown_extensions: - pymdownx.tabbed - pymdownx.superfences - pymdownx.tilde + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight - pymdownx.inlinehilite - pymdownx.highlight: @@ -99,6 +102,7 @@ markdown_extensions: copyright: Redbrick Docs + extra: github_org: https://github.com/redbrick manifest: manifest.webmanifest