From b5c27b2ed78b122095e1351a2735404c125751a0 Mon Sep 17 00:00:00 2001 From: SeaswimmerTheFsh Date: Thu, 4 Jan 2024 18:03:34 -0500 Subject: [PATCH] feat(docs): adding documentation for some cogs --- .docs/aurora.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++ .docs/nerdify.md | 19 ++++++++++ mkdocs.yml | 3 +- nerdify/nerdify.py | 26 ++++++++++++- 4 files changed, 140 insertions(+), 3 deletions(-) create mode 100644 .docs/aurora.md create mode 100644 .docs/nerdify.md diff --git a/.docs/aurora.md b/.docs/aurora.md new file mode 100644 index 0000000..87e786b --- /dev/null +++ b/.docs/aurora.md @@ -0,0 +1,95 @@ +# Aurora + +Aurora is a fully-featured moderation system. It is heavily inspired by GalacticBot, and is designed to be a more user-friendly alternative to Red's core Mod cogs. + +## Installation + +```bash +[p]repo add seacogs https://coastalcommits.com/SeaswimmerTheFsh/SeaCogs +[p]cog install seacogs aurora +[p]cog load aurora +``` + +## Commands List + +### Slash Commands + +#### Moderation Commands + +- `/note` - Add a note to a user + - Arguments: + - `target` - Accepts User IDs and mentions - This is who you're adding a note to + - `reason` - Reason for adding a note to the user + - `silent` - ***Optional*** - Toggles if the bot will try to send a direct message to the targeted user - Set to the value set by the `[p]moderationset dm` command by default +- `/warn` - Warn a user + - Arguments: + - `target` - Accepts User IDs and mentions - This is who you're warning + - `reason` - Reason for warning the user + - `silent` - ***Optional*** - Toggles if the bot will try to send a direct message to the targeted user - Set to the value set by the `[p]moderationset dm` command by default +- `/mute` - Mute a member - Doesn't work if the member is already muted! + - Arguments: + - `target` - Accepts User IDs and mentions - Must be in the discord server - This is who you're muting + - `duration` - Accepts any combination of duration units, as shown below - Maximum duration of [28 days](https://discord.com/developers/docs/resources/guild#modify-guild-member-json-params) + - ``2 d`` + - ``2 days`` + - ``1w`` + - ``1 week`` + - ``1w 4 days 3h 67minutes`` + - ``2w5d7h24m`` + - `reason` - Reason for muting the member + - `silent` - ***Optional*** - Toggles if the bot will try to send a direct message to the targeted member - Set to the value set by the `[p]moderationset dm` command by default +- `/unmute` - Unmute a member - Only works if the member is muted! + - Arguments: + - `target` - Accepts User IDs and mentions - Must be in the discord server - This is who you're unmuting + - `reason` - ***Optional*** - Reason for unmuting the member + - `silent` - ***Optional*** - Toggles if the bot will try to send a direct message to the targeted member - Set to the value set by the `[p]moderationset dm` command by default +- `/ban` - Ban a user - Doesn't work if the user is already banned + - Arguments: + - `target` - Accepts User IDs and mentions - This is who you're banning + - `reason` - Reason for banning the user + - `duration` - ***Optional*** - Accepts any combination of duration units, as shown in the mute command + - `silent` - ***Optional*** - Toggles if the bot will try to send a direct message to the targeted user - Set to the value set by the `[p]moderationset dm` command by default +- `/unban` - Unban a user - Only works if the user is banned! + - Arguments: + - `target` - Accepts User IDs and mentions - This is who you're unbanning + - `reason` - ***Optional*** - Reason for unbanning the user + - `silent` - ***Optional*** - Toggles if the bot will try to send a direct message to the targeted user - Set to the value set by the `[p]moderationset dm` command by default + +#### Case Commands + +- `/case` - Check the details of a specific case, by case number + - Arguments: + - `case_number` - Accepts case numbers - See `/history` to get a list of these + - `ephemeral` - ***Optional*** - Toggles if the response message will be hidden or not - Defaults to `false` +- `/history` - Checks the list of cases for a target, a moderator, or for the server + - Arguments - *All arguments of this command are optional*: + - `target` - Accepts User IDs and mentions - This is whose moderations you're querying - overrides `moderator` if both are given + - `moderator` - Accepts User IDs and mentions - This is the moderator whose moderations you're querying + - `pagesize` - Determines how many cases to list per `page` - Defaults to `5` - Maximum of `25` + - `page` - Determines which page to check + - `ephemeral` - Toggles if the response message will be hidden or not - Defaults to `false` + - `export` - Exports the moderation history of the entire server in a `.json` file - Defaults to `false` + - Notes: + - If `target` and `moderator` are not used, this command will query by all moderations in the server. +- `/resolve` - Resolves a case/moderation + - Arguments: + - `case_number` - Accepts case numbers - See `/history` to get a list of these + - `reason` - ***Optional*** - Reason for resolving the case + - Notes: + - If a `TEMPBAN` or `MUTE` is resolved before it expires, or a `BAN` is resolved, the targeted user will be unbanned/unmuted. + - Please resolve cases instead of unmuting/unbanning! + +### Text Commands + +- `[p]moderationset` + - This command handles the configuration for the Moderation cog + - Sub-commands: + - `[p]moderationset dm` - Server Administrator only - Per Guild + - This command toggles if the `silent` argument in Moderation slash commands will default to `true` or `false`. Defaults to `false`. + - `[p]moderationset ignorebots` - Server Administrator only - Per Guild + - This command toggles if the Moderation cog will automatically log moderations from other bots. Defaults to `false`. + - `[p]moderationset mysql` - Bot Owner only - Per Bot + - This command sends a direct message to the user with a modal to configure the MySQL settings. + - **This cog REQUIRES a configured MySQL database to function.** +- `[p]timedeltaconvert` + - Uses the same logic as `/mute` and `/unban` to generate timedeltas from human-readable input. diff --git a/.docs/nerdify.md b/.docs/nerdify.md new file mode 100644 index 0000000..b915ed3 --- /dev/null +++ b/.docs/nerdify.md @@ -0,0 +1,19 @@ +# Nerdify + +Nerdify allows you to nerdify other people's text. + +## Commands + +### `[p]nerdify` + +::: nerdify.nerdify.Nerdify.nerdify + +## Method Reference + +### `nerdify_text` + +::: nerdify.nerdify.Nerdify.nerdify_text + +### `type_message` + +::: nerdify.nerdify.Nerdify.type_message diff --git a/mkdocs.yml b/mkdocs.yml index 81eb071..507cb2d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,8 @@ site_description: Documentation for my Red-DiscordBot Cogs. nav: - Home: index.md + - Aurora: aurora.md + - Nerdify: nerdify.md plugins: - git-authors @@ -61,7 +63,6 @@ theme: - content.code.annotate - content.code.copy - navigation.instant - - navigation.tabs - search.suggest - search.highlight - search.share diff --git a/nerdify/nerdify.py b/nerdify/nerdify.py index 267b14b..cac0e7f 100644 --- a/nerdify/nerdify.py +++ b/nerdify/nerdify.py @@ -21,7 +21,15 @@ class Nerdify(commands.Cog): @commands.command(aliases=["nerd"]) async def nerdify(self, ctx: commands.Context, *, text: Optional[str] = None) -> None: - """Nerdify the replied to message, previous message, or your own text.""" + """Nerdify the replied to message, previous message, or your own text. + + Example: + ``[p]nerdify hello world!`` + > "hello world!" :nerd: + + Args: + text: The text to nerdify. If not provided, the bot will try to nerdify either the previous message or the replied to message, if the invocation message is a reply. + """ if not text: if hasattr(ctx.message, "reference") and ctx.message.reference: with suppress( @@ -43,7 +51,13 @@ class Nerdify(commands.Cog): ) def nerdify_text(self, text: str) -> str: - """Convert text to nerd speak.""" + """Convert text to nerd speak. + + Args: + text: The text to convert. + + Returns: + The converted text.""" return f"\"{text}\" 🤓" async def type_message( @@ -53,6 +67,14 @@ class Nerdify(commands.Cog): Will send a typing indicator, wait a variable amount of time based on the length of the text (to simulate typing speed), then send the message. + + Args: + destination: The [destination](https://discordpy.readthedocs.io/en/stable/api.html#discord.abc.Messageable) to send the message to. + content: The content of the message to send. + **kwargs: Any keyword arguments to pass to the [destination.send](https://discordpy.readthedocs.io/en/stable/api.html#discord.TextChannel.send) function. + + Returns: + The message sent, or None if an error occurred. """ content = common_filters.filter_urls(content) with suppress(discord.HTTPException):