From 9197fe0268b37d7efa25357ca4a7fb65e738fa75 Mon Sep 17 00:00:00 2001 From: Sheldan <5037282+Sheldan@users.noreply.github.com> Date: Mon, 11 May 2020 15:00:00 +0200 Subject: [PATCH] removed decay feature boolean from `myWarnings`, because only automatic decay is an additional feature fixed post target for kicking fixed casing for mod mail post targets added initial version of the ascii doctor documentation --- .../moderation/commands/MyWarnings.java | 2 - .../moderation/service/KickServiceBean.java | 4 +- .../myWarnings_response_embed_en_US.ftl | 3 - .../template/commands/MyWarningsModel.java | 1 - .../service/ModMailThreadServiceBean.java | 4 +- .../main/resources/config/modmail.properties | 2 +- abstracto-application/documentation/pom.xml | 76 +++++++++++ .../src/main/docs/asciidoc/features/core.adoc | 88 ++++++++++++ .../docs/asciidoc/features/experience.adoc | 43 ++++++ .../docs/asciidoc/features/moderation.adoc | 126 ++++++++++++++++++ .../main/docs/asciidoc/features/modmail.adoc | 58 ++++++++ .../main/docs/asciidoc/features/utility.adoc | 112 ++++++++++++++++ .../src/main/docs/asciidoc/main.adoc | 42 ++++++ abstracto-application/pom.xml | 1 + .../myWarnings_embed_description_en_US.ftl | 1 - .../modmail_post_target_error_en_US.ftl | 2 +- pom.xml | 4 + 17 files changed, 556 insertions(+), 13 deletions(-) create mode 100644 abstracto-application/documentation/pom.xml create mode 100644 abstracto-application/documentation/src/main/docs/asciidoc/features/core.adoc create mode 100644 abstracto-application/documentation/src/main/docs/asciidoc/features/experience.adoc create mode 100644 abstracto-application/documentation/src/main/docs/asciidoc/features/moderation.adoc create mode 100644 abstracto-application/documentation/src/main/docs/asciidoc/features/modmail.adoc create mode 100644 abstracto-application/documentation/src/main/docs/asciidoc/features/utility.adoc create mode 100644 abstracto-application/documentation/src/main/docs/asciidoc/main.adoc delete mode 100644 abstracto-application/template-config/src/main/resources/templates/en_US/commands/moderation/myWarnings/myWarnings_embed_description_en_US.ftl diff --git a/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/java/dev/sheldan/abstracto/moderation/commands/MyWarnings.java b/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/java/dev/sheldan/abstracto/moderation/commands/MyWarnings.java index b43432285..23b19bbeb 100644 --- a/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/java/dev/sheldan/abstracto/moderation/commands/MyWarnings.java +++ b/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/java/dev/sheldan/abstracto/moderation/commands/MyWarnings.java @@ -43,8 +43,6 @@ public class MyWarnings extends AbstractConditionableCommand { Long currentWarnCount = warnManagementService.getActiveWarnsForUser(commandContext.getUserInitiatedContext().getAUserInAServer()); model.setCurrentWarnCount(currentWarnCount); Long totalWarnCount = warnManagementService.getTotalWarnsForUser(commandContext.getUserInitiatedContext().getAUserInAServer()); - boolean userUsesDecay = featureFlagService.isFeatureEnabled(warningDecayFeature, commandContext.getUserInitiatedContext().getServer()); - model.setServerUsesDecays(userUsesDecay); model.setTotalWarnCount(totalWarnCount); channelService.sendTemplateInChannel("myWarnings_response", model, commandContext.getChannel()); return CommandResult.fromSuccess(); diff --git a/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/java/dev/sheldan/abstracto/moderation/service/KickServiceBean.java b/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/java/dev/sheldan/abstracto/moderation/service/KickServiceBean.java index edcffe6d0..3ab2e51c6 100644 --- a/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/java/dev/sheldan/abstracto/moderation/service/KickServiceBean.java +++ b/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/java/dev/sheldan/abstracto/moderation/service/KickServiceBean.java @@ -18,7 +18,7 @@ import java.util.Optional; public class KickServiceBean implements KickService { private static final String KICK_LOG_TEMPLATE = "kick_log"; - private static final String WARN_LOG_TARGET = "warnLog"; + private static final String KICK_LOG_TARGET = "kickLog"; @Autowired private BotService botService; @@ -43,6 +43,6 @@ public class KickServiceBean implements KickService { private void sendKickLog(KickLogModel kickLogModel) { String warnLogMessage = templateService.renderTemplate(KICK_LOG_TEMPLATE, kickLogModel); - postTargetService.sendTextInPostTarget(warnLogMessage, WARN_LOG_TARGET, kickLogModel.getServer().getId()); + postTargetService.sendTextInPostTarget(warnLogMessage, KICK_LOG_TARGET, kickLogModel.getServer().getId()); } } diff --git a/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/resources/templates/command/myWarnings/myWarnings_response_embed_en_US.ftl b/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/resources/templates/command/myWarnings/myWarnings_response_embed_en_US.ftl index 8213993b2..5f7e1e40c 100644 --- a/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/resources/templates/command/myWarnings/myWarnings_response_embed_en_US.ftl +++ b/abstracto-application/abstracto-modules/moderation/moderation-impl/src/main/resources/templates/command/myWarnings/myWarnings_response_embed_en_US.ftl @@ -9,9 +9,6 @@ "b": 255 } <#assign userMention>${member.effectiveName} - <#if serverUsesDecays> ,"description" :"<#include "myWarnings_with_decay_embed_description">" - <#else> - ,"description" :"<#include "myWarnings_embed_description">" } \ No newline at end of file diff --git a/abstracto-application/abstracto-modules/moderation/moderation-int/src/main/java/dev/sheldan/abstracto/moderation/models/template/commands/MyWarningsModel.java b/abstracto-application/abstracto-modules/moderation/moderation-int/src/main/java/dev/sheldan/abstracto/moderation/models/template/commands/MyWarningsModel.java index 66201caf9..39fae9ae7 100644 --- a/abstracto-application/abstracto-modules/moderation/moderation-int/src/main/java/dev/sheldan/abstracto/moderation/models/template/commands/MyWarningsModel.java +++ b/abstracto-application/abstracto-modules/moderation/moderation-int/src/main/java/dev/sheldan/abstracto/moderation/models/template/commands/MyWarningsModel.java @@ -9,7 +9,6 @@ import lombok.experimental.SuperBuilder; @Setter @SuperBuilder public class MyWarningsModel extends UserInitiatedServerContext { - private Boolean serverUsesDecays; private Long totalWarnCount; private Long currentWarnCount; } diff --git a/abstracto-application/abstracto-modules/modmail/modmail-impl/src/main/java/dev/sheldan/abstracto/modmail/service/ModMailThreadServiceBean.java b/abstracto-application/abstracto-modules/modmail/modmail-impl/src/main/java/dev/sheldan/abstracto/modmail/service/ModMailThreadServiceBean.java index 38978f30e..6943f3ff2 100644 --- a/abstracto-application/abstracto-modules/modmail/modmail-impl/src/main/java/dev/sheldan/abstracto/modmail/service/ModMailThreadServiceBean.java +++ b/abstracto-application/abstracto-modules/modmail/modmail-impl/src/main/java/dev/sheldan/abstracto/modmail/service/ModMailThreadServiceBean.java @@ -39,7 +39,7 @@ import java.util.concurrent.ExecutionException; public class ModMailThreadServiceBean implements ModMailThreadService { public static final String MODMAIL_CATEGORY = "modmailCategory"; - public static final String MODMAIL_LOG_POSTTARGET = "modmaillog"; + public static final String MODMAIL_LOG_POSTTARGET = "modmailLog"; @Autowired private ModMailThreadManagementService modMailThreadManagementService; @@ -143,7 +143,7 @@ public class ModMailThreadServiceBean implements ModMailThreadService { .roles(rolesToPing) .build(); MessageToSend messageToSend = templateService.renderEmbedTemplate("modmail_notification_message", modMailNotificationModel); - List> modmailping = postTargetService.sendEmbedInPostTarget(messageToSend, "modmailping", thread.getServer().getId()); + List> modmailping = postTargetService.sendEmbedInPostTarget(messageToSend, "modmailPing", thread.getServer().getId()); CompletableFuture.allOf(modmailping.toArray(new CompletableFuture[0])).whenComplete((aVoid, throwable) -> { if(throwable != null) { log.error("Failed to send mod mail thread notification ping.", throwable); diff --git a/abstracto-application/abstracto-modules/modmail/modmail-impl/src/main/resources/config/modmail.properties b/abstracto-application/abstracto-modules/modmail/modmail-impl/src/main/resources/config/modmail.properties index 2a9a3dc0e..55caa3b0b 100644 --- a/abstracto-application/abstracto-modules/modmail/modmail-impl/src/main/resources/config/modmail.properties +++ b/abstracto-application/abstracto-modules/modmail/modmail-impl/src/main/resources/config/modmail.properties @@ -1,3 +1,3 @@ -abstracto.postTargets.modmail=modmaillog,modmailping +abstracto.postTargets.modmail=modmailLog,modmailPing abstracto.emoteNames.readReaction=readReaction abstracto.defaultEmotes.readReaction=\uD83D\uDC40 \ No newline at end of file diff --git a/abstracto-application/documentation/pom.xml b/abstracto-application/documentation/pom.xml new file mode 100644 index 000000000..f3963430f --- /dev/null +++ b/abstracto-application/documentation/pom.xml @@ -0,0 +1,76 @@ + + + + abstracto-application + dev.sheldan.abstracto + 1.0-SNAPSHOT + + 4.0.0 + + dev.sheldan.abstracto.templating + documentation + pom + + + + documentation + + process-resources + + + org.asciidoctor + asciidoctor-maven-plugin + ${asciidoctor.maven.plugin.version} + + + org.asciidoctor + asciidoctorj-pdf + ${asciidoctorj.pdf.version} + + + org.jruby + jruby-complete + ${jruby.version} + + + org.asciidoctor + asciidoctorj + ${asciidoctorj.version} + + + + src/main/docs/asciidoc + main.adoc + + + + + + generate-pdf-doc + generate-resources + + process-asciidoc + + + pdf + coderay + + font + + + + - + + + + + + + + + + + + \ No newline at end of file diff --git a/abstracto-application/documentation/src/main/docs/asciidoc/features/core.adoc b/abstracto-application/documentation/src/main/docs/asciidoc/features/core.adoc new file mode 100644 index 000000000..550d6e038 --- /dev/null +++ b/abstracto-application/documentation/src/main/docs/asciidoc/features/core.adoc @@ -0,0 +1,88 @@ +=== Abstracto core feature + +The core feature contains necessary commands in order for Abstracto to function and be configured. + +.Emotes +* used as a reaction in case the command completed successfully `successReaction` +* used as a reaction in case the command did not complete successfully `warnReaction` + +.Commands +Help:: +* Usage: `help [module/command]` +* Description: If no parameter is provided, this will list the currently available modules. If the provided parameter matches the name of a module, information about that module is displayed. +This information includes a description and the available commands of this module. If the provided parameter matches a command name, information about this command is displayed. +The module matching takes precedence over command matching. +This information includes the a short description, a more detailed description, aliases (if any), parameters (if any), which roles are allowed to execute the command, +or if it is not restricted and which roles are immune against the command. +Changing emotes Abstracto uses:: +* Usage: `setEmote ` +* Description: Sets the emote identified by `key` used by Abstracto on this server to `emote`. +This allows both built in emotes and custom emotes, but the bot must be in the server of the custom emote in order to use them. +Clearing the cache:: +* Usage: `clearCache` +* Description: Clears the internal cache used by Abstrato. This is necessary if things in the databases were changed and need to be in effect immediately. +Ping:: +* Usage: `ping` +* Description: Prints the latency of Abstracto to the Discord servers. +Echo:: +* Usage: `echo ` +* Description: Echos `text` in the same channel this command as executed in. +Changing the prefix:: +* Usage: `setPrefix ` +* Description: Changes the prefix of the bot on this value to `prefix`. This can be one or multiple characters. +Changing a post target:: +* Usage: `posttarget ` +* Description: Changes the given post target identified by `key` to the given channel. All messages using this post target will be send to this channel from now on. +Listing the features:: +* Usage: `features` +* Description: Lists the available features and whether or not they are enabled in this server. +Enabling a feature:: +* Usage: `enable ` +* Description: Enables the feature identified by `key` in this server. If the feature dependents on other features, they will be enabled as well. +Disabling a feature:: +* Usage: `disable ` +* Description: Disables the feature identified by `key` in this server. If the feature is required for other features, they will be disabled as well. +Creating a channel group:: +* Usage: `createChannelGroup ` +* Description: Creates a new channel group identified by `key`. +* Aliases: `+ChGroup` +Adding a channel to a channel group:: +* Usage: `addToChannelGroup ` +* Description: Adds the `channel` to the channel group identified by the `groupName`. It is not possible for a channel to be in a group twice. +* Aliases: `addTChGrp`, `chGrpCh+` +Removing a channel from a channel group:: +* Usage: `removeFromChannelGroup ` +* Description: Removes the `channel` from the channel group identified by `groupName`. +* Aliases: `rmChChgrp`, `chGrpCh-` +Deleting a channel group:: +* Usage: `deleteChannelGroup ` +* Description: Deletes the channel group identifies by `key`. This will also remove all associated channels from this group. This command fails, if the group is used in other features and referenced. +* Aliases: `-ChGroup` +Disabling a command in a group:: +* Usage: `disableCommand ` +* Description: Disables the command identified by `commandName` in the channel group `groupName`. A command is considered disabled in a specified channel, if the command is disabled in *all* the groups the channel is in. +Enabling a command in a group:: +* Usage: `enableCommand ` +* Description: Enables the command identified by `commandName` in the channel group `groupName`. A command is considered enabled in a specified channel, if the command is enabled in *any* the groups the channel is in. +Showing all available channel groups and the respective channels:: +* Usage: `listChannelGroups` +* Description: Provides an overview of the currently available channel groups and which channels are in this channel group. +* Aliases: `lsChGrp` +Removing role restrictions from a command:: +* Usage: `allow ` +* Description: Allows everyone to execute all commands in this `feature`/the `command`. Which means, any restrictions concerning which role is able to execute a certain command is ignored even if it still shows in the help output. +Allowing a role to execute a command:: +* Usage: `allowRole ` +* Description: Allows the provided `role` to execute all commands in the `feature`/the `command`. This command automatically restricts the commands, which means, if it was unrestricted before, after executing this command only the provided role can execute the command. +Forbidding a role to execute a command:: +* Usage: `disAllowRole ` +* Description: Removes the `role` from the list of allowed roles for all commands in the `feature`/the `command`. +Make a role affected by a command:: +* Usage: `makeAffected ` +* Description: Makes the role affected by all commands in the `feature`/the `command`. +Make a role immune against a command:: +* Usage: `makeImmune ` +* Description: Makes the role immune from all commands in the `feature`/the `command`. +Enforce the role restrictions of commands:: +* Usage: `restrict ` +* Description: Causes the role restrictions for a all commands in the `feature`/the `command` to be in effect again. \ No newline at end of file diff --git a/abstracto-application/documentation/src/main/docs/asciidoc/features/experience.adoc b/abstracto-application/documentation/src/main/docs/asciidoc/features/experience.adoc new file mode 100644 index 000000000..04928cce4 --- /dev/null +++ b/abstracto-application/documentation/src/main/docs/asciidoc/features/experience.adoc @@ -0,0 +1,43 @@ +=== Experience tracking feature + +This feature contains the ability to track experience of users on the server and award roles based on the level they reach. +The experience is awarded once per minute and is calculated by asciimath:[`\text{rand}(\text{minExp}, \text{maxExp}) * \text{expScale}`]. +Only one role is awarded at a time and the past unlocked roles are not given to the members. + +.Relevant system configuration +`minExp` The lower bound of the awarded base experience. Default: 10. + +`maxExp` The upper bound of the awarded base experience Default: 25. + +`expScale` The multiplier applied after the experience amount was determined. Default: 1.0. + +.Commands +Changing the experience scale of the server:: +* Usage: `expScale ` +* Description: Changes the value of `expScale` on this server to `value`. + +Showing the leader board of the server:: +* Usage: `leaderboard [page]` +* Description: Shows the leader board of the server in a paginated format. This does not use the interactive pagination. +If no parameter is provided, it will show the top 10 members and their message count, level, experience and rank. +Additionally the same information for the user executing is shown, regardless whether or not the user is already shown on the given leader board page. +If a `page` is provided, it will display the leader board of the ranks `page * 10` until `(page + 1) * 10` instead. If `page` is beyond the member count, the last members are shown. + + +Setting a role to be awarded at a certain level:: +* Usage: `setExpRole ` +* Description: Sets `role` to be awarded at the given `level`. If the role was previously assigned, +this will cause to remove this assignment and recalculate the roles for all users previously having this role. +This command will provide a status message indicating this process. +This will not award this role to users which qualify for this, a `syncRoles` is necessary for this. + +Syncing the roles of the members with the configuration:: +* Usage: `syncRoles` +* Description: Recalculates the appropriate levels for all users on the server and awards the roles appropriate for the level. +There will be a message indicating the current status of the progress and it is highly advised to not execute this command while another instance is still processing. +This command can run for a longer period of time, depending on the amount of members in the guild. + +Remove a role from being awarded at a certain level:: +* Usage: `unSetExpRole ` +* Description: Removes this role from the experience tracking, removes the role from all members previously owning it and recalculates their new role according to the configuration. +This will provide a status update message displaying the process. \ No newline at end of file diff --git a/abstracto-application/documentation/src/main/docs/asciidoc/features/moderation.adoc b/abstracto-application/documentation/src/main/docs/asciidoc/features/moderation.adoc new file mode 100644 index 000000000..36256f392 --- /dev/null +++ b/abstracto-application/documentation/src/main/docs/asciidoc/features/moderation.adoc @@ -0,0 +1,126 @@ +=== Moderation +This feature is split into sub features and they can be enabled individually. + +* Moderation +* Warnings +** Warn decay +* Logging +* Muting + +[.lead] +Moderation + +Feature key: `moderation` + +.Post targets +`banLog`:: Will be used to send a log message containing information about the ban for both `ban` and `banId`. Will still ban if not setup. +`kickLog`:: Will be used to send a log message containing information about the kick. Will still kick if not setup. + +.Commands +Ban a member:: +* Usage: `ban [reason]` +* Description: +Bans the given given `member` with the given optional `reason`. This sends a logging message to the `banLog` post target. +Banning this way does not delete old messages of the member on the server. If the `reason` is not provided, a default reason is used. +* Required bot permission: `BAN_MEMBERS` +Ban a user by ID:: +* Usage: `banId [reason]` +* Description: Bans the `user` by his id with the optional `reason`. . This command can be used in case the user is not part of the server anymore. +This will also send a log message to `banLog` and not delete old messages. +* Required bot permission: `BAN_MEMBERS` +Kick a member:: +* Usage: `kick [reason]` +* Description: Kicks the `member` from the guild with the given `reason`. If the `reason` is not provided, a default reason is used. +* Required bot permission: `KICK_MEMBERS` +Change the slow mode in a channel:: +* Usage: `slowmode [channel]` +* Description: This command sets the slow mode in the `channel` to the given `duration`. This command uses duration parsing. The `channel` is optional and if none is provided, the current channel is used. +* Required bot permission: `MANAGE_CHANNEL` in the respective channel + +[.lead] +Warning + +This feature can be used to warn specific users if they did something not allowed by the rules. + +Feature key: `warnings` + +.Post targets +`warnLog`:: Will be used to send a log message containing information about the warn. +`decayLog`:: Will be used when all the warnings are decayed by a command and logging has been selected. + +.Commands +Warn a user:: +* Usage: `warn [reason]` +* Description: Warns the `member` with the given `reason` or a default one, if none is provided. This command sends a log message to the `warnLog` post +target and notifies the member about the warn. +Listing the warnings of users:: +* Usage: `warnings [member]` +* Description: If no `member` is provided displays all the warnings on the server. If a `member` is provided, will only display the warnings of the user. +This uses a paginated output, which means multiple pages in case there are more warnings to display. This will also display the date the warning was decayed if applicable. +Showing your warnings:: +* Usage: `myWarnings` +* Description: Displays the warnings of the user executing on the server. This will show both active and total warnings. +Decaying all warnings regardless of the date:: +* Usage: `decayAllWarnings [writeLog]` +* Description: This will cause all warnings of this server which are not decayed yet to be decayed instantly. If this command should log the decaying of the warnings +the `writeLog` parameter needs to be `true`. +Deleting a warning:: +* Usage: `deleteWarning ` +* Description: Deletes the warning identified by `warnId` completely from the database. + + +[.lead] +Automatic warn decay + +This feature enables warnings to be decayed after a configurable amount of days. This feature directly depends on the feature `warnings`. + +Feature key: `warnDecay` + +.Relevant system configuration +`decayDays` The amount of days after which a warning gets decayed. Default: 90 + +.Post targets +`decayLog`:: Will be used to send the log message containing the information in case a warning is decayed. + +.Commands +Decaying all warnings if necessary:: +* Usage: `decayWarnings` +* Description: Triggers the decay of the warnings instantly, which means, every not decayed warning on this server older than the configured amount of days will be decayed and the decay will be logged. + +[.lead] +Muting + +This feature provides the capability to mute users, which effectively means it applies a role which prevents them from sending messages and speaking in voice chat. +The role used to mute member will not be created and needs to be provided. There is no validation if the provided role actually mutes members. +If the user leaves the guild and rejoins, the mute role will be re-applied. + +Feature key `muting` + +.Post targets +`muteLog`:: Will be used to send the log message containing the information in case a member was muted and when the mute ended automatically. + +.Commands +Muting a user:: +* Usage: `mute [reason]` +* Description: Applies the mute role to the given `member` for the given `duration`. If `reason` is not provided, a default reason will be used for logging in the `muteLog` post target. This will automatically +un-mute the user after the duration has passed. If the un-mute happens automatically, this will also be logged in the `muteLog` post target. +This command sends a notification to the user about the mute and kicks the user from the voice channel, if any. +Un-Muting a user:: +* Usage: `unMute ` +* Description: Removes the mute role from the given member. This does *not* log the un-mute. +Configuring which role to use for muting:: +* Usage: `setMuteRole ` +* Description: Sets the `role` to be used as the role when applying a mute. This role needs to be muting, which means, if you want it to be effective, this role needs to deny `MESSAGE_WRITE`. Abstracto does not validate nor require the role to actually mute. +Only *one* role can be used as a mute role. + +[.lead] +Logging + +This feature provides a range of utilities to monitor the server. +The logging includes: + +Deleted message logging:: When a message is deleted, the content of the message and the possible attachments of said message will be logged. Post target `deleteLog`. +Edited message logging:: When a message is edited, the previous content of the message and the new content of the message will be logged. +This does not work if the message was sent before the bot was started. Post target `editLog`. +Member joining logging:: When a member joins the guild, a message indicating this is send. Post target `joinLog`. +Member leaving logging:: When a member leaves the guild, a message indicating this is send. Post target `leaveLog`. diff --git a/abstracto-application/documentation/src/main/docs/asciidoc/features/modmail.adoc b/abstracto-application/documentation/src/main/docs/asciidoc/features/modmail.adoc new file mode 100644 index 000000000..1a48ec72c --- /dev/null +++ b/abstracto-application/documentation/src/main/docs/asciidoc/features/modmail.adoc @@ -0,0 +1,58 @@ +=== Mod mail feature + +This feature enables users to contact the moderation of the server in a private manner. This can be initiated by messaging the Abstracto bot. + + +==== Workflow +* User messages the Abstracto bot +* If Abstracto is active in multiple servers with mod mail enabled, the user is prompted to which server he wants to open a mod mail thread for. +* A channel in the mod mail category is created for the user and notification is sent that a new mod mail thread has been opened +* User can send messages in the private channel and they get relayed to this created text channel. +* Moderators can answer in the thread with the respective commands +* Moderators close the thread +* The interactions between the user and the moderators gets logged in the mod mail logging channel + +Feature key: `modmail` + +.Post targets +`modmailLog`:: Will be used to log the interactions when a thread is closed. +`modmailPing`:: Will be used to send the notification when a new thread is opened. + + +.Emotes +* used to indicate to the user that the message sent was processed `readReaction` + +.Commands +Opening a mod mail thread for a user:: +* Usage: `contact ` +* Description: Creates a new mod mail thread with the `member`. Does not send a notification about the new thread. +Replying to a mod mail thread:: +* Usage `reply [text]` +* Description: Sends `text` to the user if provided. `text` is optional, because its also possible to only send a picture. +Replying anonymously to a mod mail thread:: +* Usage: `anonReply [text]` +* Description: Sends `text` to the user without showing how is the author. Instead the avatar and name of Abstracto will be used. +Enabling notifications of messages sent by the user:: +* Usage: `subscribe` +* Description: Subscribes you to the current thread, and will ping you when a new message from the member arrives. +Disabling notifications of messages sent by the user:: +* Usage: `unSubscribe` +* Description: Removes your subscription from the current thread, and you will no longer be notified when a message from the member arrives. +Closing the mod mail thread:: +* Usage: `close [note]` +* Description: Closes the thread, deletes the text channel containing the thread and logs the interactions between the member and the moderators in the `modmailLog` post target. +When closing a thread, a closing header with general information will be send and the note will be displayed there. +When a thread is closed this way the user is notified of this. +Closing the mod mail thread without notifying the user:: +* Usage: `closeSilently [note]` +* Description: Closes the thread, deletes the text channel containing the thread and logs the interactions between the member and the moderators in the `modmailLog` post target. +When closing a thread, a closing header with general information will be send and the note will be displayed there. +Adding a role to the roles responsible for managing mod mail threads:: +* Usage: `setModMailRole ` +* Description: Adds this role to the roles responsible for mod mail threads, which means: this role will be pinged when a new thread is created and this role is automatically added to the roles allowed to execute all commands related to mod mail. +Removing a role from the roles responsible for managing mod mail threads:: +* Usage: `removeModMailRole ` +* Description: Removes this role from the roles responsible for mod mail threads, which means: this role will no longer be pinged when a new thread is created and this role will also be removed from the roles allowed to execute all commands related to mod mail. +Changing the category in which the text channels are created:: +* Usage: `setModMailCategory ` +* Description: Sets the category which Abstracto uses to create the text channels containing the mod mail threads. The existing threads will not be migrated automatically. diff --git a/abstracto-application/documentation/src/main/docs/asciidoc/features/utility.adoc b/abstracto-application/documentation/src/main/docs/asciidoc/features/utility.adoc new file mode 100644 index 000000000..2932a9002 --- /dev/null +++ b/abstracto-application/documentation/src/main/docs/asciidoc/features/utility.adoc @@ -0,0 +1,112 @@ +=== Utility + +This feature is split into sub features: + +* Reminders +* Starboard +* Suggestions +* Utility +* Link embeds + +[.lead] +Reminders + +Provides the ability to schedule reminders. + +Feature key: `remind` + +.Commands +Create a reminder:: +* Usage: `remind ` +* Description: Creates a reminder with `text` which will be triggered after `duration`. This command uses duration parsing. The reminder will ping when the duration has passed and provide +the context of the reminder. +Cancelling a reminder:: +* Usage `unRemind ` +* Description: Cancels this reminder reminder and will cause this reminder to not be executed. +Listing all active reminders:: +* Usage: `reminders` +* Description: Lists all the currently not yet executed reminders and information about each of them. + + +[.lead] +Starboard + +Provides the ability to track note worthy posts in a separate channel, identified by the post target `starboard`, because the pins within a channel are limited to 50. +This feature works by users reacting to a message with the appropriate emote. By default this is `⭐`, but can be changed via the emote `star`. +There is a configurable threshold a message needs to reach in order to be posted to starboard. +The post in the starboard is continuously updated and depending on the current star count an associated emote is displayed. +When the poster of the message reacts to the message with a star, this is not counted. When the post is deleted from the starboard, the original message cannot appear on the starboard again. + +Feature key: `starboard` + +.Emotes +* to vote on posting something to starboard: `star` +* for the different level of starboard posts: +** Level 1: `star1` +** Level 2: `star2` +** Level 3: `star3` +** Level 4: `star4` +* used as badges in the `starStats` command: +** First place: `starboardBadge1` +** Second place: `starboardBadge2` +** Third place: `starboardBadge3` + +.Relevant system configuration +`starLvl1` The amount of stars necessary to appear on the starboard. Default: 5 + +`starLvl2` The amount of stars necessary in order for the level 2 emote to be used in the starboard post. Default: 8 + +`starLvl3` The amount of stars necessary in order for the level 3 emote to be used in the starboard post. Default: 13 + +`starLvl4` The amount of stars necessary in order for the level 4 emote to be used in the starboard post. Default: 17 + +.Commands +Showing starboard statistics:: +* Usage `starStats` +* Description: Shows the most starred posts, the member with the most received stars and the members rewarding the most stars. + +[.lead] +Suggestions + +This feature provides the ability for members to post suggestions containing text to the post target `suggestions`. These suggestions can then be accepted or denied by the moderators. + +Feature key: `suggestion` + +.Emotes +* used for up-voting a suggestion: `suggestionYes` +* used for down-voting a suggestion: `suggestionNo` + +.Commands +Creating a suggestion:: +* Usage `suggest ` +* Description: Posts the text to the `suggest` post target and places the emotes for up and down voting. +Accepting a suggestion:: +* Usage `accept [note]` +* Description: Re-posts the suggestion identified by `suggestionId` and marks the suggestion as accepted. The optional `note` will be used in this re-post, if provided. +Deny a suggestion:: +* Usage `deny [note]` +* Description: Re-posts the suggestion identified by `suggestionId` and marks the suggestion as denied. The optional `note` will be used in this re-post, if provided. + +[.lead] +Utility + +This feature provides some utility commands. + +Feature key: `utility` + +.Commands +Retrieving the URL of an emote:: +* Usage `showEmote ` +* Description: Posts the name of the emote accompanied with the URL where the image of the emote is stored. + +.lead] +Link embeds + +.Emotes +* used to remove the embed of a link: `removeEmbed` + +This feature enables the automatic embedding of messages containing a message link. +If a message contains a link to a discord message this will create an embed containing the the message content. This supports image attachments, but not videos or files. +A reaction is placed on the embedded message can be used to delete this embed. Only the person posting the message link and the person being quoted can use this feature. + +Feature key: `link_embeds` \ No newline at end of file diff --git a/abstracto-application/documentation/src/main/docs/asciidoc/main.adoc b/abstracto-application/documentation/src/main/docs/asciidoc/main.adoc new file mode 100644 index 000000000..e44d551b9 --- /dev/null +++ b/abstracto-application/documentation/src/main/docs/asciidoc/main.adoc @@ -0,0 +1,42 @@ += Abstracto Discord Bot Documentation +Sheldan https://github.com/Sheldan +1.0, May 10, 2020 +:toc: +:icons: font + +Abstracto is a feature rich Discord bot written in Java and uses JDA as the wrapper for the Discord API. +This documentation is split into two parts: Technical documentation and user documentation. + +== User documentation + +== Glossary + +Post target:: Describes the channel where Abstracto will send specific messages to. For example, the command `ban` sends a message containing information about the ban to the `banLog` post target. +Post targets can be configured with the command `posttarget` and once defined can only be switched to another channel. +Decayed warnings:: Warnings have a decayed property, which means it can be marked as inactive, while the warning itself is not deleted. + +== General information + +Duration input:: This procedure is done when a command requires a duration as an input, for example `mute`. +In order to define a duration: use a positive number followed by one of the following time units: `s`, `m`, `h`, `d` or `w` representing seconds, minutes, hours, days and weeks respectively. +Weeks in this case are just a short hand for 7 days. +Pagination navigation:: If a pagination is used for the output of a command you can navigate the pages with `◀️` and `▶️` and `⏹️` to close the pagination. +Role as parameter:: Whenever a role is a parameter for a command, this can be done by either providing the role ID or mentioning the role. +Channel groups:: This concept enables you to group channels together into channel groups and enact certain restrictions or features on this whole group. +System configuration:: Some properties can be configured while the bot is running. +In the respective features they are noted under `Relevant system configuration`. +In order to change this you need to use the command `setConfig` with the provided key and the new desired value. +Emotes:: The features have section of the keys of used emotes in the feature, you can change this emote with the `setEmote` command. + +== Features +The following features are available, and they can be enabled/disabled with the command `enable`/`disable`. + +include::features/core.adoc[] + +include::features/moderation.adoc[] + +include::features/modmail.adoc[] + +include::features/experience.adoc[] + +include::features/utility.adoc[] diff --git a/abstracto-application/pom.xml b/abstracto-application/pom.xml index b2a239a76..345dd67f6 100644 --- a/abstracto-application/pom.xml +++ b/abstracto-application/pom.xml @@ -21,6 +21,7 @@ abstracto-modules scheduling template-config + documentation diff --git a/abstracto-application/template-config/src/main/resources/templates/en_US/commands/moderation/myWarnings/myWarnings_embed_description_en_US.ftl b/abstracto-application/template-config/src/main/resources/templates/en_US/commands/moderation/myWarnings/myWarnings_embed_description_en_US.ftl deleted file mode 100644 index f3057bf57..000000000 --- a/abstracto-application/template-config/src/main/resources/templates/en_US/commands/moderation/myWarnings/myWarnings_embed_description_en_US.ftl +++ /dev/null @@ -1 +0,0 @@ -${userMention} has currently ${totalWarnCount} warnings in total. \ No newline at end of file diff --git a/abstracto-application/template-config/src/main/resources/templates/en_US/modMail/exception/modmail_post_target_error_en_US.ftl b/abstracto-application/template-config/src/main/resources/templates/en_US/modMail/exception/modmail_post_target_error_en_US.ftl index d07f8f8ae..15c761a0d 100644 --- a/abstracto-application/template-config/src/main/resources/templates/en_US/modMail/exception/modmail_post_target_error_en_US.ftl +++ b/abstracto-application/template-config/src/main/resources/templates/en_US/modMail/exception/modmail_post_target_error_en_US.ftl @@ -1 +1 @@ -Post target `modmaillog` was not found. \ No newline at end of file +Post target `modmailLog` was not found. \ No newline at end of file diff --git a/pom.xml b/pom.xml index 1d3037a89..e853b219f 100644 --- a/pom.xml +++ b/pom.xml @@ -20,6 +20,10 @@ 4.1.1_126 3.0.3 + 2.0.0-RC.1 + 1.5.3 + 2.3.0 + 9.2.11.1