From af24120f2ad7f891c6439bdc089cef1523d0a4d2 Mon Sep 17 00:00:00 2001 From: nova <110734810+novanai@users.noreply.github.com> Date: Tue, 5 Nov 2024 17:07:33 +0000 Subject: [PATCH] Update webgroup docs (#48) * Remove duplicate webgroup title * Update blockbot docs * Fix indentation --- docs/index.md | 2 -- docs/webgroup/blockbot.md | 66 +++++++++++++++++++++-------------- docs/webgroup/contributing.md | 16 ++++----- 3 files changed, 47 insertions(+), 37 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5fada4a..0eafc60 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,8 +24,6 @@ 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 diff --git a/docs/webgroup/blockbot.md b/docs/webgroup/blockbot.md index 3f3eb95..71d64b7 100644 --- a/docs/webgroup/blockbot.md +++ b/docs/webgroup/blockbot.md @@ -46,42 +46,44 @@ As a prerequisite, you need to have an application registered on the Discord dev 2. Go to *"Bot"* on the left sidebar, click `Reset Token`. 3. Copy the newly generated token. -### Source Code +### Running from source (deprecated) + +1. Fork, `git clone` and `cd` into the [blockbot repository](https://github.com/redbrick/blockbot). + + > [!TIP] + > Read the [contributing docs](./contributing.md) for more information on using Git and GitHub. -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 -``` + ```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= -``` + ``` + TOKEN= + ``` 4. Run `pip install -r requirements.txt` to install the required packages. 5. Start the bot by running `python3 -m src`. -### Docker +### Running with Docker Compose + +1. Fork, `git clone` and `cd` into the [blockbot repository](https://github.com/redbrick/blockbot). + + > [!TIP] + > Read the [contributing docs](./contributing.md) for more information on using Git and GitHub. -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` +2. Rename `.env.sample` to `.env` inside the repo folder and fill in the environment variables with your secrets. e.g.: + + ``` + TOKEN= + ``` + +3. Run the `compose.yaml` file: `docker compose up --build` ## Library Resources @@ -109,7 +111,9 @@ TOKEN= * [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`? +## FAQ + +### 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) @@ -125,7 +129,7 @@ TOKEN= * 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`? +### 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. @@ -133,7 +137,7 @@ TOKEN= **Further reading:** -## What's the difference between `hikari.GatewayBot`, `arc.GatewayClient` and `miru.Client`? +### 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 @@ -152,3 +156,11 @@ TOKEN= ## Do's and Don'ts * Always try to get data from the cache before fetching it from the API. + + ```py + # command example + async def command(ctx: arc.GatewayContext) -> None: + user = ctx.client.cache.get_user(123) + if not user: + user = await ctx.client.rest.fetch_user(123) + ``` diff --git a/docs/webgroup/contributing.md b/docs/webgroup/contributing.md index 2d9e0e3..5ae365c 100644 --- a/docs/webgroup/contributing.md +++ b/docs/webgroup/contributing.md @@ -27,18 +27,18 @@ title: Contributing to Webgroup - 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. + > [!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 "" + git add + git commit -m "" ``` -> [!TIP] -> See [Writing Meaningful Commit Messages](https://reflectoring.io/meaningful-commit-messages/) + > [!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. @@ -53,5 +53,5 @@ git commit -m "" ![Pull Request page on GitHub](../res/pull-request.png) -> [!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. + > [!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.