Skip to content

Commit 2a66877

Browse files
wizzdomnovanaiHypnoAnt
authored
add initial webgroup docs (#24)
* add initial webgroup docs * add blockbot docs * add contributing doc skeleton * Update blockbot docs * Update wording & formatting * Add blockbot technical documentation * Add webgroup contribution docs * Link to webgroup on index page * add obsidian-style callouts and metadata * Docker Info --------- Co-authored-by: nova <[email protected]> Co-authored-by: hypnoant <[email protected]>
1 parent 06608db commit 2a66877

9 files changed

+240
-0
lines changed

‎docs/.pages

+1
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ nav:
44
- procedures
55
- hardware
66
- services
7+
- webgroup
78
- contact.md

‎docs/index.md

+4
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ This is mostly intended for admins, future admins, webmasters, and everybody els
2424

2525
## Webgroup
2626

27+
## Webgroup
28+
29+
The [webgroup](webgroup/index.md) is a subgroup of Redbrick consisting of volunteers who work with the webmaster on a number of projects.
30+
2731
## New Admins
2832

2933
So, you want to become an admin. Brave of you. Here's some stuff you should probably read:

‎docs/res/branches.png

104 KB
Loading

‎docs/res/contribute.png

128 KB
Loading

‎docs/res/pull-request.png

163 KB
Loading

‎docs/webgroup/blockbot.md

+154
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
id: blockbot
3+
aliases:
4+
- Blockbot
5+
tags:
6+
- webgroup
7+
- discord
8+
title: Blockbot
9+
---
10+
11+
# Blockbot
12+
13+
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.
14+
15+
## File Structure
16+
17+
All bot files are under `src/`.
18+
19+
- `bot.py`
20+
- Contains the bot configuration and instantiation (e.g. loading the bot extensions).
21+
- `extensions/`
22+
- 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/).
23+
- `examples/`
24+
- Contains example extensions with commands, components and more as reference for developers.
25+
- `config.py`
26+
- 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.
27+
- `utils.py`
28+
- Utility functions are stored here, that can be reused across the codebase.
29+
30+
## Installation
31+
32+
> [!TIP]
33+
> Docker Compose for local development is highly reccommended. This is similar to how it is deployed on Redbrick.
34+
35+
### Discord Developer Portal
36+
37+
As a prerequisite, you need to have an application registered on the Discord developer portal.
38+
39+
1. Create a Discord application [here](https://discord.com/developers/applications/).
40+
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`).
41+
3. Go to the generated URL and invite the application to the desired server.
42+
43+
#### Bot Token
44+
45+
1. Open the application on the Discord developer portal.
46+
2. Go to *"Bot"* on the left sidebar, click `Reset Token`.
47+
3. Copy the newly generated token.
48+
49+
### Source Code
50+
51+
1. `git clone` and `cd` into the [blockbot repository](https://github.com/redbrick/blockbot).
52+
2. It is generally advised to work in a Python [virtual environment](https://docs.python.org/3/library/venv.html):
53+
54+
```sh
55+
python3 -m venv .venv
56+
source .venv/bin/activate
57+
```
58+
59+
3. Rename `.env.sample` to `.env` inside the repo folder and fill in the environment variables with your secrets. e.g.:
60+
61+
```
62+
TOKEN=<Discord bot token here>
63+
```
64+
65+
4. Run `pip install -r requirements.txt` to install the required packages.
66+
5. Start the bot by running `python3 -m src`.
67+
68+
### Docker
69+
70+
1. `git clone` and `cd` into this repository.
71+
2. Create a new file called `.env` inside the repo folder and paste your bot token into the file as such:
72+
```
73+
TOKEN=<Discord bot token here>
74+
```
75+
3. Build the docker image `docker build --tag "blockbot-testing" .`
76+
4. Run this image `docker run "blockbot-testing"`
77+
78+
### Docker Compose
79+
1. `git clone` and `cd` into this repository.
80+
2. Create a new file called `.env` inside the repo folder and paste your bot token into the file as such:
81+
```
82+
TOKEN=<Discord bot token here>
83+
```
84+
3. Run the docker-compose.yml file `docker-compose up -d`
85+
86+
## Library Resources
87+
88+
- [`hikari` Documentation](https://docs.hikari-py.dev/en/latest/)
89+
- [`hikari` Examples](https://github.com/hikari-py/hikari/tree/master/examples)
90+
- [`hikari-arc` Documentation](https://arc.hypergonial.com/)
91+
- [`hikari-arc` Examples](https://github.com/hypergonial/hikari-arc/tree/main/examples/gateway)
92+
- [`hikari-miru` Documentation](https://miru.hypergonial.com/)
93+
- [`hikari-miru` Examples](https://github.com/hypergonial/hikari-miru/tree/main/examples)
94+
95+
## Usage Guides
96+
97+
### hikari
98+
99+
* [Getting Started](https://hg.cursed.solutions/#getting-started) - first steps of using `hikari`
100+
* [Events](https://hg.cursed.solutions/01.events/) - understanding receiving events from Discord with `hikari`
101+
102+
### hikari-arc
103+
104+
* [Getting Started](https://arc.hypergonial.com/getting_started/) - first steps of using `hikari-arc`
105+
* [Guides](https://arc.hypergonial.com/guides/) - various guides on aspects of `hikari-arc`
106+
107+
### hikari-miru
108+
109+
* [Getting Started](https://miru.hypergonial.com/getting_started/) - first steps of using `hikari-miru`
110+
* [Guides](https://miru.hypergonial.com/guides/) - various guides on aspects of `hikari-miru`
111+
112+
## What's the difference between `hikari`, `hikari-arc` and `hikari-miru`?
113+
114+
* `hikari` - the Discord API wrapper. Can be used to, for example:
115+
* [add roles to server members](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.add_role_to_member)
116+
* [create threads](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.create_thread)
117+
* [send individual messages](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.create_message)
118+
* [fetch guild (server) information](https://docs.hikari-py.dev/en/stable/reference/hikari/api/rest/#hikari.api.rest.RESTClient.fetch_guild)
119+
* 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))
120+
* 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)
121+
* `hikari-arc` - the command handler. Can be used to:
122+
* create application commands ([slash](https://arc.hypergonial.com/guides/options/#declaring-options), [message & user commands](https://arc.hypergonial.com/guides/context_menu/))
123+
* respond to command interactions
124+
* `hikari-miru` - the component handler. Can be used to:
125+
* create message components (buttons, select menus & modals)
126+
* respond to component interactions (button clicks, select menu selections & modal submissions)
127+
128+
## Why use a `hikari.GatewayBot` instead of a `hikari.RESTBot`?
129+
130+
**TL;DR:** `RESTBot`s do not receive events required for some blockbot features (e.g. starboard), so `GatewayBot` must be used instead.
131+
132+
`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).
133+
134+
**Further reading:** <https://arc.hypergonial.com/getting_started/#difference-between-gatewaybot-restbot>
135+
136+
## What's the difference between `hikari.GatewayBot`, `arc.GatewayClient` and `miru.Client`?
137+
138+
* `hikari.GatewayBot` is the actual Discord bot. It:
139+
* manages the websocket connection to Discord
140+
* sends HTTP requests to the Discord REST API
141+
* caches information received in events sent by Discord
142+
* `arc.GatewayClient` adds additional functionality to `hikari.GatewayBot` for:
143+
* splitting the bot across multiple files using [extensions](https://arc.hypergonial.com/guides/plugins_extensions/#extensions)
144+
* grouping commands using [plugins](https://arc.hypergonial.com/guides/plugins_extensions/#plugins)
145+
* easily creating and managing commands and [command groups](https://arc.hypergonial.com/guides/command_groups/)
146+
* accessing objects globally (in any extension, plugin or command) using [dependency injection](https://arc.hypergonial.com/guides/dependency_injection/) (e.g. a database connection)
147+
* `miru.Client` adds additional functionality to `hikari.GatewayBot` for:
148+
* creating message components using [views](https://miru.hypergonial.com/getting_started/#first-steps)
149+
* creating [modals](https://miru.hypergonial.com/guides/modals/)
150+
* creating [navigators](https://miru.hypergonial.com/guides/navigators/) and [menus](https://miru.hypergonial.com/guides/menus/) using views
151+
152+
## Do's and Don'ts
153+
154+
* Always try to get data from the cache before fetching it from the API.

‎docs/webgroup/contributing.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
id: contributing
3+
aliases:
4+
- Contributing to Webgroup
5+
- contributing
6+
tags:
7+
- webgroup
8+
title: Contributing to Webgroup
9+
---
10+
11+
# Contributing to Webgroup
12+
13+
## Basic Contribution Workflow
14+
15+
- Fork the repository on GitHub.
16+
- Clone your fork of the repository.
17+
18+
```bash
19+
git clone <your fork URL>
20+
```
21+
22+
- Switch to a new branch (name it appropriately!)
23+
24+
```bash
25+
git checkout -b <new branch name>
26+
```
27+
28+
- Make changes to the codebase.
29+
30+
> [!NOTE]
31+
> 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.
32+
33+
- Stage and commit the changes.
34+
35+
```bash
36+
git add <files you changed>
37+
git commit -m "<commit message>"
38+
```
39+
40+
> [!NOTE] Tip
41+
> See [Writing Meaningful Commit Messages](https://reflectoring.io/meaningful-commit-messages/)
42+
43+
- On GitHub, navigate to your fork repository and switch to the branch you created.
44+
45+
![Branches on GitHub](../res/branches.png)
46+
47+
- Use the ":material-source-pull: Contribute" button to open the pull request page.
48+
49+
![Contribution modal on GitHub](../res/contribute.png)
50+
51+
- 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.
52+
53+
![Pull Request page on GitHub](../res/pull-request.png)
54+
55+
56+
> [!NOTE] Tip
57+
> 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.

‎docs/webgroup/index.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
id: webgroup
3+
aliases:
4+
- Webgroup
5+
tags:
6+
- webgroup
7+
title: Webgroup
8+
---
9+
10+
# Webgroup
11+
12+
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.
13+
14+
Read more about how the webgroup operates in [open governance](https://redbrick.dcu.ie/open-governance/webgroup/webgroup.html).
15+
16+
## Webgroup Projects
17+
18+
### [Blockbot](blockbot.md)
19+
20+
A Discord bot, written in Python, that is maintained by the Redbrick Webgroup.

‎mkdocs.yml

+4
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,9 @@ markdown_extensions:
8484
- pymdownx.tabbed
8585
- pymdownx.superfences
8686
- pymdownx.tilde
87+
- pymdownx.emoji:
88+
emoji_index: !!python/name:material.extensions.emoji.twemoji
89+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
8790
- pymdownx.highlight
8891
- pymdownx.inlinehilite
8992
- pymdownx.highlight:
@@ -99,6 +102,7 @@ markdown_extensions:
99102

100103
copyright: <img class="logo" src="/res/logo.png" width="20px"> <a href="https://docs.redbrick.dcu.ie"><strong>Redbrick Docs</strong></a>
101104

105+
102106
extra:
103107
github_org: https://github.com/redbrick
104108
manifest: manifest.webmanifest

0 commit comments

Comments
 (0)