diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80f63e1a..471ab1db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,6 +73,8 @@ There are separate cog files for each activity, and one [`__init__.py`](cogs/__i * [`cogs/__init__.py`](cogs/__init__.py): instantiates all the cog classes within this directory +* [`cogs/annual_handover_and_reset.py`](cogs/annual_handover_and_reset.py): cogs for annual handover procedures and role resets + * [`cogs/archive.py`](cogs/archive.py): cogs for archiving categories of channels within your group's Discord guild * [`cogs/command_error.py`](cogs/command_error.py): cogs for sending error messages when commands fail to complete/execute @@ -81,10 +83,14 @@ There are separate cog files for each activity, and one [`__init__.py`](cogs/__i * [`cogs/edit_message.py`](cogs/edit_message.py): cogs for editing messages that were previously sent by TeX-Bot +* [`cogs/get_token_authorisation.py`](cogs/get_token_authorisation.py): cogs for retrieving the current status of the supplied authentication token + * [`cogs/induct.py`](cogs/induct.py): cogs for inducting people into your group's Discord guild * [`cogs/kill.py`](cogs/kill.py): cogs related to the shutdown of TeX-Bot +* [`cogs/make_applicant`](cogs/make_applicant.py): cogs related to making users into applicants + * [`cogs/make_member.py`](cogs/make_member.py): cogs related to making guests into members * [`cogs/ping.py`](cogs/ping.py): cog to request a [ping](https://wikipedia.org/wiki/Ping-pong_scheme#Internet) response @@ -221,3 +227,23 @@ If you see an error, we encourage you to **be bold** and fix it yourself, rather If you are stuck, need help, or have a question, the best place to ask is on our Discord. Happy contributing! + + + + + + + + +## Guides + +### Creating a New Cog + + +### Creating a New Environment Variable + + +### Creating a Response Button + + + diff --git a/README.md b/README.md index 719fe7b3..e72dfce7 100644 --- a/README.md +++ b/README.md @@ -14,40 +14,6 @@ This is a [Discord bot](https://discord.com/developers/docs/topics/oauth2#bot-vs Featured in the [CSS Discord guild](https://cssbham.com/discord). -## Terminology - -### ["Guild"](https://discord.com/developers/docs/resources/guild) Vs ["Server"](https://wikipedia.org/wiki/Discord#Servers) - -Confusingly, [Discord](https://discord.com) uses the term ["guild"](https://discord.com/developers/docs/resources/guild) to refer to a [Discord "server"](https://wikipedia.org/wiki/Discord#Servers), when communicating with developers. -Therefore, the same terminology (["guild"](https://discord.com/developers/docs/resources/guild)) will be used across all documentation in this project. -(See [the Discord developer docs](https://discord.com/developers/docs/resources/guild) & [Pycord's docs](https://docs.pycord.dev/en/stable/api/models.html#discord.Guild) for more information.) - -The term "main guild" is used throughout the code in this repository to refer specifically to your community group's main [Discord guild](https://discord.com/developers/docs/resources/guild). - -### "User" Vs "Member" Vs "Guest" - -#### [Discord Objects](https://discord.com/developers/docs) - -In the context of [Discord](https://discord.com) itself, a ["user"](https://discord.com/developers/docs/resources/user) object represents a [Discord](https://discord.com) account not connected to any specific [guild](https://discord.com/developers/docs/resources/guild). -Therefore, it can be [messaged via DM](https://dictionary.com/browse/dm) or be retrieved via its [snowflake ID](https://discord.com/developers/docs/reference#snowflakes), but little else can be done with it. -(See [the Discord developer docs](https://discord.com/developers/docs/resources/user) & [Pycord's docs](https://docs.pycord.dev/en/stable/api/models.html#users) for more information.) - -In contrast, a [Discord "member" object](https://discord.com/developers/docs/resources/guild#guild-member-object) is a [user](https://discord.com/developers/docs/resources/user) attached to a specific [guild](https://discord.com/developers/docs/resources/guild). -Therefore, it can have [roles](https://discord.com/developers/docs/topics/permissions#role-object), be [banned](https://discord.com/developers/docs/resources/guild#ban-object) & have many other actions applied to it. -(See [the Discord developer docs](https://discord.com/developers/docs/resources/guild#guild-member-object) & [Pycord's docs](https://docs.pycord.dev/en/stable/api/models.html#discord.Member) for more information.) - -#### Community Group Membership - -In the context of your community group's membership structure, a "member" is a person that has purchased a membership to join your community group. -This is in contrast to a "guest", which is a person that has not purchased a membership. -Guests often can only attend events that are open to anyone (i.e. **not** members only), and have limited communication/perks within your [Discord guild](https://discord.com/developers/docs/resources/guild). -Some commands may require you to create [roles](https://discord.com/developers/docs/topics/permissions#role-object) within your [Discord guild](https://discord.com/developers/docs/resources/guild), to differentiate between these different types of users. - -#### Other Uses - -In some other contexts, the term "user" may be used to refer to any person/organisation making use of this project. -(E.g. the description within [the "Error Codes" section](#error-codes).) - ## Error Codes Users of TeX-Bot may encounter an error code when executing a slash-command fails. @@ -167,15 +133,7 @@ A full guide on how to create your bot's account can be found [here; on Pycord's You'll need to create a [Discord bot](https://discord.com/developers/docs/topics/oauth2#bot-vs-user-accounts) of your own in the [Discord Developer Portal](https://discord.com/developers/applications). It's also handy if you have an empty [guild](https://discord.com/developers/docs/resources/guild) for you to test in. -You can retrieve the correct [invite URL](https://docs.pycord.dev/en/stable/discord.html#inviting-your-bot) to use by navigating to the root folder, then running the following command: - -```shell -poetry run python -m utils generate_invite_url {discord_bot_application_id} {discord_guild_id} -``` - -* `{discord_bot_application_id}` must be replaced by the [application ID](https://discord.com/developers/applications) of your [bot](https://discord.com/developers/docs/topics/oauth2#bot-vs-user-accounts) - -* `{discord_guild_id}` must be replaced by the [snowflake ID](https://discord.com/developers/docs/reference#snowflakes) of your community group's [guild](https://discord.com/developers/docs/resources/guild) +You can retrieve the correct [invite URL](https://docs.pycord.dev/en/stable/discord.html#inviting-your-bot) by simply running TeX-Bot for the first time with DEBUG logging enabled, and the invite url will be printed to the console. ### Setting [Environment Variables](https://wikipedia.org/wiki/Environment_variable) diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md new file mode 100644 index 00000000..94044f3d --- /dev/null +++ b/TERMINOLOGY.md @@ -0,0 +1,89 @@ +# TeX-Bot-Py-V2 Terminology + +## ["Guild"](https://discord.com/developers/docs/resources/guild) Vs ["Server"](https://wikipedia.org/wiki/Discord#Servers) + +Confusingly, [Discord](https://discord.com) uses the term ["guild"](https://discord.com/developers/docs/resources/guild) to refer to a [Discord "server"](https://wikipedia.org/wiki/Discord#Servers), when communicating with developers. +Therefore, the same terminology (["guild"](https://discord.com/developers/docs/resources/guild)) will be used across all documentation in this project. +(See [the Discord developer docs](https://discord.com/developers/docs/resources/guild) & [Pycord's docs](https://docs.pycord.dev/en/stable/api/models.html#discord.Guild) for more information.) + +The term "main guild" is used throughout the code in this repository to refer specifically to your community group's main [Discord guild](https://discord.com/developers/docs/resources/guild). + + +## [Interactions](https://discord.com/developers/docs/interactions/overview) + + + + + + +## [Application Commands](https://discord.com/developers/docs/interactions/application-commands) + + +An [Application Command](https://discord.com/developers/docs/interactions/application-commands) can be a [Slash Command](#slash-commands), [Message Command](#message-commands) or [User Command](#user-commands). + +Bots are limited to only 100 [Slash Commands](#slash-commands), 5 [Message Commands](#message-commands) and 5 [User Commands](#user-commands). + +The primary difference is the way these commands are triggered. [Slash Commands](#slash-commands) are triggered by sending a message into the chat, while both [User Commands](#user-commands) and [Message Commands](#message-commands) are triggered via a UI context menu provided by right-clicking on a [User](https://discord.com/developers/docs/resources/user) or [Message](https://discord.com/developers/docs/resources/message) respectively. + + +### [Slash Commands](https://discord.com/developers/docs/interactions/application-commands#slash-commands) + + +Slash commands, also known as `CHAT_INPUT` commands are executed via sending a chat message and are made up of a name, description and a set of options. These can be defined using the `discord.slash_command` decorator as follows: +```python +@discord.slash_command( + name="command-name", + description="a description of what the command does", +) +async def command_name(self, ctx: TeXBotApplicationContext): + """Doc string goes here.""" + pass # command functions go here +``` + + +For more example usages, check the [Guides](CONTRIBUTING#Guides) section of the [CONTRIBUTING](CONTRIBUTING.md) doc. + + +### Context Commands + +#### [Message Commands](https://discord.com/developers/docs/interactions/application-commands#message-commands) + + +Message commands, also known as `Message-Context Commands`, are executed via right-clicking on a [Message](https://discord.com/developers/docs/resources/message), clicking "Apps", then selecting the command from the menu. + +The main difference between [Context Commands](#context-commands) and [Slash Commands](#slash-commands) is that [Context Commands](#context-commands) do not take user defined arguments and are limited to the [Message](https://discord.com/developers/docs/resources/message) that the command is issued on and the context which is passed along side it. + + +#### [User Commands](https://discord.com/developers/docs/interactions/application-commands#user-commands) + + + +## "User" Vs "Member" Vs "Guest" + +### [Discord Objects](https://discord.com/developers/docs) + +In the context of [Discord](https://discord.com) itself, a ["user"](https://discord.com/developers/docs/resources/user) object represents a [Discord](https://discord.com) account not connected to any specific [guild](https://discord.com/developers/docs/resources/guild). +Therefore, it can be [messaged via DM](https://dictionary.com/browse/dm) or be retrieved via its [snowflake ID](https://discord.com/developers/docs/reference#snowflakes), but little else can be done with it. +(See [the Discord developer docs](https://discord.com/developers/docs/resources/user) & [Pycord's docs](https://docs.pycord.dev/en/stable/api/models.html#users) for more information.) + +In contrast, a [Discord "member" object](https://discord.com/developers/docs/resources/guild#guild-member-object) is a [user](https://discord.com/developers/docs/resources/user) attached to a specific [guild](https://discord.com/developers/docs/resources/guild). +Therefore, it can have [roles](https://discord.com/developers/docs/topics/permissions#role-object), be [banned](https://discord.com/developers/docs/resources/guild#ban-object) & have many other actions applied to it. +(See [the Discord developer docs](https://discord.com/developers/docs/resources/guild#guild-member-object) & [Pycord's docs](https://docs.pycord.dev/en/stable/api/models.html#discord.Member) for more information.) + +### Community Group Membership + +In the context of your community group's membership structure, a "member" is a person that has purchased a membership to join your community group. +This is in contrast to a "guest", which is a person that has not purchased a membership. +Guests often can only attend events that are open to anyone (i.e. **not** members only), and have limited communication/perks within your [Discord guild](https://discord.com/developers/docs/resources/guild). +Some commands may require you to create [roles](https://discord.com/developers/docs/topics/permissions#role-object) within your [Discord guild](https://discord.com/developers/docs/resources/guild), to differentiate between these different types of users. + +### Other Uses + +In some other contexts, the term "user" may be used to refer to any person/organisation making use of this project. +(E.g. the description within [the "Error Codes" section](#error-codes).) + + + + + +