diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 47089935..7dac3446 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -88,3 +88,38 @@ jobs: fail_ci_if_error: true path_to_write_report: ./coverage/codecov_report.txt verbose: true + + documentation: + runs-on: ubuntu-latest + if: | + (github.event_name == 'pull_request_target' && github.actor == 'dependabot[bot]') || + (github.event_name != 'pull_request_target' && github.actor != 'dependabot[bot]') + steps: + - name: checkout repo content + uses: actions/checkout@v2 + - name: setup python + uses: actions/setup-python@v2 + with: + python-version: 3.8 + - name: Install dependencies + run: | + pip install pysqlcipher3 + python -m pip install --upgrade pip + pip install flake8 pytest + pip install pytest-cov + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: Create new json documentation + env: + ENCRYPTED: "False" + BOT_OWNER: ${{ secrets.BOT_OWNER }} + DISCORD_TOKEN: ${{ secrets.DISCORD_TOKEN }} + GMAIL_EMAIL: ${{ secrets.GMAIL_EMAIL }} + GMAIL_PASSWORD: ${{ secrets.GMAIL_PASSWORD }} + TWITCH_SECRET: ${{ secrets.TWITCH_SECRET }} + TWITCH_TOKEN: ${{ secrets.TWITCH_TOKEN }} + run: | + python ./GenerateDoc.py + - name: commit changes + uses: EndBug/add-and-commit@v7 # You can change this to use a specific version + with: + push: true \ No newline at end of file diff --git a/Documentation.json b/Documentation.json new file mode 100644 index 00000000..11504a22 --- /dev/null +++ b/Documentation.json @@ -0,0 +1,417 @@ +[ + { + "name": "KoalaBot", + "commands": [ + { + "command": "listExt", + "parameters": [], + "description": "Lists all enabled and disabled Koala Extensions on your server" + }, + { + "command": "enableExt", + "parameters": ["koala_extension"], + "description": "Enable a Koala Extension on your server" + }, + { + "command": "disableExt", + "parameters": ["koala_extension"], + "description": "Disable a Koala Extension on your server" + }, + { + "command": "welcomeUpdateMsg", + "parameters": [], + "description": "Change the customisable part of the welcome message of your server" + }, + { + "command": "welcomeSendMsg", + "parameters": [], + "description": "Sends out the welcome message manually to all members of your server" + }, + { + "command": "welcomeViewMsg", + "parameters": [], + "description": "Shows this server's current welcome message" + }, + { + "command": "clear", + "parameters": ["amount"], + "description": "Clears a given number of messages from the channel." + }, + { + "command": "ping", + "parameters": [], + "description": "Returns the ping of a bot" + }, + { + "command": "support", + "parameters": [], + "description": "Returns a link to the KoalaBot Support Discord Server" + } + ] + }, + { + "name": "Announce", + "commands": [ + { + "command": "announce create", + "parameters": [], + "description": "Create a new message that will be available for sending" + }, + { + "command": "changeTitle", + "parameters": [], + "description": "Change the title of the embedded message" + }, + { + "command": "changeContent", + "parameters": [], + "description": "Change the content of the embedded message" + }, + { + "command": "addRole", + "parameters": [], + "description": "Add a role to list of people to send the announcement to" + }, + { + "command": "removeRole", + "parameters": [], + "description": "Remove a role from a list of people to send the announcement to" + }, + { + "command": "preview", + "parameters": [], + "description": "Post a constructed embedded message to the channel where the command is invoked" + }, + { + "command": "send", + "parameters": [], + "description": "Send a pending announcement" + }, + { + "command": "cancel", + "parameters": [], + "description": "Cancel a pending announcement" + } + ] + }, + { + "name": "ColourRole", + "commands": [ + { + "command": "customColour", + "parameters": ["colour_hexcode/'no'"], + "description": "Gives a user a chosen custom colour, or removes the custom colour with 'k!customColour no'" + }, + { + "command": "listProtectedRoleColours", + "parameters": [], + "description": "Lists the protected roles, whose colours are protected from being imitated by a custom colour, in a server" + }, + { + "command": "addProtectedRoleColour", + "parameters": ["role"], + "description": "Adds a role's colour to the list of protected roles" + }, + { + "command": "removeProtectedRoleColour", + "parameters": ["role"], + "description": "Removes a role's colour from the list of protected roles" + }, + { + "command": "listCustomColourAllowedRoles", + "parameters": [], + "description": "Lists the roles in a server whose users are permitted to have their own custom colours" + }, + { + "command": "addCustomColourAllowedRole", + "parameters": ["role"], + "description": "Adds a role to the list of roles allowed to have a custom colour" + }, + { + "command": "removeCustomColourAllowedRole", + "parameters": ["role_str"], + "description": "Removes a role from the list of roles allowed to have a custom colour" + } + ] + }, + { + "name": "ReactForRole (RFR)", + "commands": [ + { + "command": "rfr create", + "parameters": [], + "description": "Create a new, blank rfr message. Default title is React for Role. Default description is Roles below!" + }, + { + "command": "rfr delete", + "parameters": [], + "description": "Delete an existing rfr message" + }, + { + "command": "rfr addRequiredRole", + "parameters": ["role"], + "description": "Add a server-wide role required to react to/use rfr functionality. If no role is added, anyone can use rfr functionality" + }, + { + "command": "rfr removeRequiredRole", + "parameters": ["role"], + "description": "Removes a server-wide role from the group of roles someone requires to use rfr functionality" + }, + { + "command": "rfr listRequiredRoles", + "parameters": [], + "description": "Lists the server-specific role permissions for using rfr functionality" + }, + { + "command": "rfr edit description", + "parameters": [], + "description": "Edit the description of an existing rfr message" + }, + { + "command": "rfr edit title", + "parameters": [], + "description": "Edit the title of an existing rfr message" + }, + { + "command": "rfr edit thumbnail", + "parameters": [], + "description": "Edit the thumbnail of an existing rfr message" + }, + { + "command": "rfr edit inline", + "parameters": [], + "description": "Edit the inline property of embed fields in rfr embeds" + }, + { + "command": "rfr edit addRoles", + "parameters": [], + "description": "Add emoji/role combos to an existing rfr message" + }, + { + "command": "rfr edit removeRoles", + "parameters": [], + "description": "Remove emoji/role combos from an existing rfr message" + }, + { + "command": "rfr edit fixEmbed", + "parameters": [], + "description": "Cosmetic fix method if the bot ever has a moment and doesn't react with the correct emojis/has duplicates" + } + ] + }, + { + "name": "TextFilter", + "commands": [ + { + "command": "filter", + "parameters": ["text", "type"], + "description": "Filter a word or string of text. Type is defaulted to 'banned' which will delete the message and warn the user. Use type 'risky' to just warn the user" + }, + { + "command": "filterRegex", + "parameters": ["regex", "type"], + "description": "Filter a regex string. Type is defaulted to 'banned' which will delete the message and warn the user. Use type 'risky' to just warn the user" + }, + { + "command": "filterList", + "parameters": [], + "description": "Get a list of filtered words in the server" + }, + { + "command": "modChannelAdd", + "parameters": ["channelId"], + "description": " Add a mod channel for receiving filtered message information (User, Timestamp, Message) to be sent to" + }, + { + "command": "modChannelRemove", + "parameters": ["channelId"], + "description": "Remove a mod channel from the server" + }, + { + "command": "modChannelList", + "parameters": [], + "description": "See a list of mod channels in the server" + }, + { + "command": "ignoreUser", + "parameters": ["userMention"], + "description": "Add a new ignored user for the server. This users' messages will be ignored by the Text Filter" + }, + { + "command": "ignoreChannel", + "parameters": ["channelMention"], + "description": "Add a new ignored channel for the server. Messages in this channel will be ignored by the Text Filter" + }, + { + "command": "ignoreList", + "parameters": [], + "description": "See a list of ignored users/channels in the server" + }, + { + "command": "unfilter", + "parameters": ["text"], + "description": "Unfilter a word/string/regex of text that was previously filtered" + }, + { + "command": "unignore", + "parameters": ["mention"], + "description": "Unignore a user/channel that was previously set as ignored" + } + ] + }, + { + "name": "TwitchAlert", + "commands": [ + { + "command": "twitchAdd", + "parameters": ["channel_id", "twitch_username", "custom_live_message"], + "description": "Add a Twitch user to a Twitch Alert" + }, + { + "command": "twitchRemove", + "parameters": ["channel_id", "twitch_username"], + "description": "Remove a user from a Twitch Alert" + }, + { + "command": "twitchAddTeam", + "parameters": ["channel_id", "team_name", "custom_live_message"], + "description": "Add a Twitch team to a Twitch alert" + }, + { + "command": "twitchRemoveTeam", + "parameters": ["channel_id", "team_name"], + "description": "Edit the default message put in a Twitch Alert Notification" + }, + { + "command": "twitchEditMsg", + "parameters": ["channel", "default_live_message"], + "description": "Edit the default message put in a Twitch Alert Notification" + }, + { + "command": "twitchViewMsg", + "parameters": ["channel"], + "description": "Shows the current default message for Twitch Alerts" + }, + { + "command": "twitchList", + "parameters": ["channel"], + "description": "Shows all current TwitchAlert users and teams in a channel" + } + ] + }, + { + "name": "Verify", + "commands": [ + { + "command": "verifyAdd", + "parameters": ["suffix", "role"], + "description": "Set up a role and email pair for KoalaBot to verify users with" + }, + { + "command": "verifyRemove", + "parameters": ["suffix", "role"], + "description": "Disable an existing verification listener" + }, + { + "command": "reVerify", + "parameters": ["role"], + "description": "Removes a role from all users who have it and marks them as needing to re-verify before giving it back." + }, + { + "command": "verifyList", + "parameters": ["channelId"], + "description": "List the current verification setup for the server" + }, + { + "command": "verify", + "parameters": ["email"], + "description": "Send to KoalaBot in dms to verify an email with our system" + }, + { + "command": "unVerify", + "parameters": ["email"], + "description": "Send to KoalaBot in dms to un-verify an email with our system" + }, + { + "command": "confirm", + "parameters": ["token"], + "description": "Send to KoalaBot in dms to confirm the verification of an email" + } + ] + }, + { + "name": "Vote", + "commands": [ + { + "command": "vote create", + "parameters": ["title"], + "description": "Creates a new vote" + }, + { + "command": "vote addRole", + "parameters": ["role"], + "description": "Adds a role to the list of roles the vote will be sent to" + }, + { + "command": "vote removeRole", + "parameters": ["role"], + "description": "Removes a role to the list of roles the vote will be sent to" + }, + { + "command": "vote setChair", + "parameters": ["chair_user"], + "description": "Sets the chair of a vote (no chair defaults to message the channel)" + }, + { + "command": "vote setChannel", + "parameters": ["channel"], + "description": "Sets the target voice channel of a vote (Users connected to this channel will receive the vote message)" + }, + { + "command": "vote addOption", + "parameters": ["option"], + "description": "Adds an option to the current vote (separate the title and description with a '+' e.g. option title+option description)" + }, + { + "command": "vote removeOption", + "parameters": ["index"], + "description": "Removes an option from a vote based on it's index" + }, + { + "command": "vote setEndTime", + "parameters": ["time_string"], + "description": "Sets a specific time for the vote to end. Results will be sent to the chair or owner if you use this, not a channel" + }, + { + "command": "vote preview", + "parameters": [], + "description": "Generates a preview of what users will see with the current configuration of the vote" + }, + { + "command": "vote cancel", + "parameters": ["title"], + "description": "Cancels a vote you are setting up or have sent" + }, + { + "command": "vote list", + "parameters": [], + "description": "Return a list of all votes you have in this server" + }, + { + "command": "vote send", + "parameters": [], + "description": "Sends a vote to all users within the restrictions set with the current options added" + }, + { + "command": "vote close", + "parameters": ["title"], + "description": "Ends a vote, and collects the results" + }, + { + "command": "vote checkResults", + "parameters": ["title"], + "description": "Checks the results of a vote without closing it" + } + ] + } +] diff --git a/GenerateDoc.py b/GenerateDoc.py new file mode 100644 index 00000000..b84c3ff5 --- /dev/null +++ b/GenerateDoc.py @@ -0,0 +1,187 @@ +from os import listdir, path +from inspect import getmembers, isclass +import re +import json + +""" +KoalaBot utility function for auto generating bot command docs +Created By: Charlie Bowe, Aqeel Little +""" + +class DocumentationEntry: + """Class for storing documentation entries for bot commands + """ + name = None + params = [] + desc = None + + def __init__(self,name: str,params,desc: str): + self.name = name + self.params = params + self.desc = desc + +class CogDocumentation: + """Stores a list of documentation entries for a cog + """ + name = None + docs = [] + + #Dictionary of cogs that have different names in the doc for clarity + docNameChanges = { + 'BaseCog': 'KoalaBot', + 'ReactForRole': 'ReactForRole (RFR)', + 'Verification': 'Verify', + 'Voting': 'Vote' + } + + def __init__(self,name: str, docs): + #If name of the cog is not the name that should be in the doc + if name in self.docNameChanges.keys(): + #change it + self.name = self.docNameChanges.get(name) + else: + self.name = name + self.docs = docs + +def add_cog_to_cog(add,to,docList): + """Add all DocumentationEntry of one CogDocumentation to another + :param add: CogDocumentation to move and destroy + :param to: CogDocumentation to add to + :param docList: list of CogDocumentation that add and to are in + :return: new list of CogDocumentation + """ + addCog = None + toCog = None + + for doc in docList: + if doc.name == add: + addCog = doc + elif doc.name == to: + toCog = doc + + if(addCog != None) and (toCog != None): + docList.remove(addCog) + toCog.docs.extend(addCog.docs) + + return docList + +def get_cog_docs(): + """Imports all cogs in directory cogs and stores the name, params and + docstring description of bot commands + :return: list of CogDocumentation + """ + #List fo Cogdocumentation + docList = [] + #Get the directory of the cogs folder + dir = path.join(path.dirname(path.realpath(__file__)),'cogs') + #Grab the names of all the .py files in the cogs folder + modules = [] + modules = [ fl for fl in listdir(dir) if fl.endswith('.py') ] + cogs = [] + + #for i in range 0 to amount of cogs + for i in range (0,len(modules)): + if modules[i].endswith('.py'): + modules[i] = modules[i][:-3] + + #Import the library and store it in cogs + cogs.append(__import__('cogs.'+modules[i])) + + #get the refernce to the current library + #E.g. cogs.Announce + currentLib = getattr(cogs[i], modules[i]) + + #Store all of the classes of the cog in classes + classes = [ obj for obj in getmembers(currentLib) if isclass(obj[1]) ] + + #list of DocumentationEntry for each class + docs = [] + for cls in classes: + #Store the functions of each classes in class_funcs + class_funcs = [ obj for obj in getmembers(cls[1]) ] + + for obj in class_funcs: + try: + #Get the docstring of the function + text = getattr(getattr(currentLib,modules[i]),str(obj[0])).help.splitlines() + except AttributeError: + #On attribute error, function has no docstring + pass + continue + except Exception: + print(f'Error {Exception} when reading docstring of {obj} in {modules[i]}') + continue + + #Get the name of the command object + name = getattr(getattr(currentLib,modules[i]),str(obj[0])).name + + #If function is nested, append its nested commadn to its font + #E.g. announce create + if getattr(getattr(currentLib,modules[i]),str(obj[0])).parent != None: + name = f'{getattr(getattr(currentLib,modules[i]),str(obj[0])).parent} {name}' + + desc = "" + params = [] + for line in text: + #Match each line to regex for checking for parameter descriptions + matchObj = re.match( r':(.*) (.*): (.*)', line, re.M|re.I) + + #If its a parameter + if matchObj and (matchObj.group(1) == 'param'): + #Do not add it if its a ctx, as that is not useful for the doc + if matchObj.group(2) == 'ctx': + continue + params.append(matchObj.group(2)) + else: + #Else, its a description of the command, so add it to desc + desc += line + #Create a new Documentation entry for the command + docs.append(DocumentationEntry(name,params,desc)) + + docList.append(CogDocumentation(modules[i],docs)) + + #Add everything in IntroCog to KoalaBot for clarity + docList = add_cog_to_cog('IntroCog','KoalaBot',docList) + + return docList + +def doc_list_to_json(docList): + """Converts a list of CogDocumentation into a json string + :param docList: List fo CogDocumentation + :return: JSON string + """ + data = [] + for cogDoc in docList: + cog = {} + cog['name'] = cogDoc.name + commands = [] + for docEntry in cogDoc.docs: + entry = {} + entry['command'] = docEntry.name + entry['parameters'] = docEntry.params + entry['description'] = docEntry.desc + commands.append(entry) + cog['commands'] = commands + data.append(cog) + return data + +def parse_docs(docList, filename): + """Pass a list of CogDocumentation objects into a json file + :param docList: List of CogDocumentation + :param filename: filename of json file + """ + data = doc_list_to_json(docList) + file = open(filename, "w") + file.write(json.dumps(data, indent=2)) + file.close() + +def generate_doc(): + """Runs the script that will automatically generate documentation.json using the docstrings + of cogs in directory cogs + """ + docList = get_cog_docs() + parse_docs(docList,'documentation.json') + +if __name__ == "__main__": + print('Generating document.json') + generate_doc() \ No newline at end of file diff --git a/KoalaBot.py b/KoalaBot.py index a27b84f1..7cd23237 100644 --- a/KoalaBot.py +++ b/KoalaBot.py @@ -33,6 +33,8 @@ from utils.KoalaDBManager import KoalaDBManager as DBManager from utils.KoalaUtils import error_embed +from GenerateDoc import generate_doc + # Constants logging.basicConfig(filename='KoalaBot.log') logging.getLogger().addHandler(logging.StreamHandler(sys.stdout)) @@ -110,6 +112,9 @@ def load_all_cogs(): Loads all cogs in COGS_DIR into the client """ UNRELEASED = [] + + #Auto generate documentation.json + generate_doc() for filename in os.listdir(COGS_DIR): if filename.endswith('.py') and filename not in UNRELEASED: diff --git a/documentation.json b/documentation.json index 11504a22..3df6853b 100644 --- a/documentation.json +++ b/documentation.json @@ -1,417 +1,625 @@ [ { - "name": "KoalaBot", + "name": "Announce", "commands": [ { - "command": "listExt", + "command": "announce addRole", "parameters": [], - "description": "Lists all enabled and disabled Koala Extensions on your server" + "description": "Add a role to list of people to send the announcement to:return:" }, { - "command": "enableExt", - "parameters": ["koala_extension"], - "description": "Enable a Koala Extension on your server" + "command": "announce", + "parameters": [], + "description": "Use k!announce create to create an announcement" }, { - "command": "disableExt", - "parameters": ["koala_extension"], - "description": "Disable a Koala Extension on your server" + "command": "announce cancel", + "parameters": [], + "description": "Cancel a pending announcement:return:" }, { - "command": "welcomeUpdateMsg", + "command": "announce changeContent", "parameters": [], - "description": "Change the customisable part of the welcome message of your server" + "description": "Change the content of the embedded message:return:" }, { - "command": "welcomeSendMsg", + "command": "announce changeTitle", "parameters": [], - "description": "Sends out the welcome message manually to all members of your server" + "description": "Change the title of the embedded message:return:" }, { - "command": "welcomeViewMsg", + "command": "announce create", "parameters": [], - "description": "Shows this server's current welcome message" + "description": "Create a new message that will be available for sending:return:" }, { - "command": "clear", - "parameters": ["amount"], - "description": "Clears a given number of messages from the channel." + "command": "announce preview", + "parameters": [], + "description": "Post a constructed embedded message to the channel where the command is invoked:return:" }, { - "command": "ping", + "command": "announce removeRole", "parameters": [], - "description": "Returns the ping of a bot" + "description": "Remove a role from a list of people to send the announcement to:return:" }, { - "command": "support", + "command": "announce send", "parameters": [], - "description": "Returns a link to the KoalaBot Support Discord Server" + "description": "Send a pending announcement:return:" } ] }, { - "name": "Announce", + "name": "TwitchAlert", "commands": [ { - "command": "announce create", - "parameters": [], - "description": "Create a new message that will be available for sending" - }, - { - "command": "changeTitle", - "parameters": [], - "description": "Change the title of the embedded message" + "command": "twitchAddTeam", + "parameters": [ + "raw_channel_id", + "team_name", + "custom_live_message" + ], + "description": "Add a Twitch team to a Twitch Alert:return:" }, { - "command": "changeContent", - "parameters": [], - "description": "Change the content of the embedded message" + "command": "twitchAdd", + "parameters": [ + "raw_channel_id", + "twitch_username", + "custom_live_message" + ], + "description": "Add a Twitch user to a Twitch Alert:return:" }, { - "command": "addRole", - "parameters": [], - "description": "Add a role to list of people to send the announcement to" + "command": "twitchEditMsg", + "parameters": [ + "raw_channel_id", + "default_live_message" + ], + "description": "Edit the default message put in a Twitch Alert Notificationleave empty for program default:return:" }, { - "command": "removeRole", + "command": "twitchList", "parameters": [], - "description": "Remove a role from a list of people to send the announcement to" + "description": "Shows all current TwitchAlert users and teams in a channel:param ctx::param raw_channel_id::return:" }, { - "command": "preview", - "parameters": [], - "description": "Post a constructed embedded message to the channel where the command is invoked" + "command": "twitchRemoveTeam", + "parameters": [ + "raw_channel_id", + "team_name" + ], + "description": "Removes a team from a Twitch Alert:return:" }, { - "command": "send", - "parameters": [], - "description": "Send a pending announcement" + "command": "twitchRemove", + "parameters": [ + "raw_channel_id", + "twitch_username" + ], + "description": "Removes a user from a Twitch Alert:return:" }, { - "command": "cancel", - "parameters": [], - "description": "Cancel a pending announcement" + "command": "twitchViewMsg", + "parameters": [ + "raw_channel_id" + ], + "description": "Shows the current default message for Twitch Alertsleave empty for program default:return:" } ] }, { - "name": "ColourRole", + "name": "Verify", "commands": [ { - "command": "customColour", - "parameters": ["colour_hexcode/'no'"], - "description": "Gives a user a chosen custom colour, or removes the custom colour with 'k!customColour no'" + "command": "verifyList", + "parameters": [], + "description": "List the current verification setup for the server:return:" }, { - "command": "listProtectedRoleColours", - "parameters": [], - "description": "Lists the protected roles, whose colours are protected from being imitated by a custom colour, in a server" + "command": "confirm", + "parameters": [ + "token" + ], + "description": "Send to KoalaBot in dms to confirm the verification of an email:return:" }, { - "command": "addProtectedRoleColour", - "parameters": ["role"], - "description": "Adds a role's colour to the list of protected roles" + "command": "verifyRemove", + "parameters": [ + "suffix", + "role" + ], + "description": "Disable an existing verification listener:return:" }, { - "command": "removeProtectedRoleColour", - "parameters": ["role"], - "description": "Removes a role's colour from the list of protected roles" + "command": "verifyAdd", + "parameters": [ + "suffix", + "role" + ], + "description": "Set up a role and email pair for KoalaBot to verify users with:return:" }, { - "command": "listCustomColourAllowedRoles", - "parameters": [], - "description": "Lists the roles in a server whose users are permitted to have their own custom colours" + "command": "getEmails", + "parameters": [ + "user_id" + ], + "description": "See the emails a user is verified with:return:" }, { - "command": "addCustomColourAllowedRole", - "parameters": ["role"], - "description": "Adds a role to the list of roles allowed to have a custom colour" + "command": "reVerify", + "parameters": [ + "role" + ], + "description": "Removes a role from all users who have it and marks them as needing to re-verify before giving it back:return:" }, { - "command": "removeCustomColourAllowedRole", - "parameters": ["role_str"], - "description": "Removes a role from the list of roles allowed to have a custom colour" + "command": "unVerify", + "parameters": [ + "email" + ], + "description": "Send to KoalaBot in dms to un-verify an email with our system:return:" + }, + { + "command": "verify", + "parameters": [ + "email" + ], + "description": "Send to KoalaBot in dms to verify an email with our system:return:" } ] }, { - "name": "ReactForRole (RFR)", + "name": "KoalaBot", "commands": [ { - "command": "rfr create", - "parameters": [], - "description": "Create a new, blank rfr message. Default title is React for Role. Default description is Roles below!" + "command": "activity", + "parameters": [ + "new_activity", + "name" + ], + "description": "Change the activity of the bot" }, { - "command": "rfr delete", - "parameters": [], - "description": "Delete an existing rfr message" + "command": "clear", + "parameters": [ + "amount" + ], + "description": "Clears a given number of messages from the given channel" }, { - "command": "rfr addRequiredRole", - "parameters": ["role"], - "description": "Add a server-wide role required to react to/use rfr functionality. If no role is added, anyone can use rfr functionality" + "command": "disableExt", + "parameters": [ + "koala_extension" + ], + "description": "Disables a koala extension onto a server" }, { - "command": "rfr removeRequiredRole", - "parameters": ["role"], - "description": "Removes a server-wide role from the group of roles someone requires to use rfr functionality" + "command": "enableExt", + "parameters": [ + "koala_extension" + ], + "description": "Enables a koala extension onto a server, all grants all extensions" }, { - "command": "rfr listRequiredRoles", + "command": "listExt", "parameters": [], - "description": "Lists the server-specific role permissions for using rfr functionality" + "description": "Lists the enabled koala extensions of a server" }, { - "command": "rfr edit description", - "parameters": [], - "description": "Edit the description of an existing rfr message" + "command": "loadCog", + "parameters": [ + "extension" + ], + "description": "Loads a cog from the cogs folder" }, { - "command": "rfr edit title", + "command": "ping", "parameters": [], - "description": "Edit the title of an existing rfr message" + "description": "Returns the ping of the bot" }, { - "command": "rfr edit thumbnail", + "command": "support", "parameters": [], - "description": "Edit the thumbnail of an existing rfr message" + "description": "KoalaBot Support server link" }, { - "command": "rfr edit inline", - "parameters": [], - "description": "Edit the inline property of embed fields in rfr embeds" + "command": "unloadCog", + "parameters": [ + "extension" + ], + "description": "Unloads a running cog" }, { - "command": "rfr edit addRoles", + "command": "welcomeSendMsg", "parameters": [], - "description": "Add emoji/role combos to an existing rfr message" + "description": "Allows admins to send out their welcome message manually to all members of a guild. Has a 60 second cooldown perguild." }, { - "command": "rfr edit removeRoles", - "parameters": [], - "description": "Remove emoji/role combos from an existing rfr message" + "command": "welcomeUpdateMsg", + "parameters": [ + "new_message" + ], + "description": "Allows admins to change their customisable part of the welcome message of a guild. Has a 60 second cooldown perguild." }, { - "command": "rfr edit fixEmbed", + "command": "welcomeViewMsg", "parameters": [], - "description": "Cosmetic fix method if the bot ever has a moment and doesn't react with the correct emojis/has duplicates" + "description": "Shows this server's current welcome message" } ] }, { - "name": "TextFilter", + "name": "Vote", "commands": [ { - "command": "filter", - "parameters": ["text", "type"], - "description": "Filter a word or string of text. Type is defaulted to 'banned' which will delete the message and warn the user. Use type 'risky' to just warn the user" + "command": "vote addOption", + "parameters": [ + "option_string" + ], + "description": "Adds an option to the current voteseparate the title and description with a \"+\" e.g. option title+option description" }, { - "command": "filterRegex", - "parameters": ["regex", "type"], - "description": "Filter a regex string. Type is defaulted to 'banned' which will delete the message and warn the user. Use type 'risky' to just warn the user" + "command": "vote addRole", + "parameters": [ + "role" + ], + "description": "Adds a role to the list of roles the vote will be sent toIf no roles are added, the vote will go to all users in a guild (unless a target voice channel has been set)" }, { - "command": "filterList", + "command": "vote removeOption", + "parameters": [ + "index" + ], + "description": "Removes an option from a vote based on it's index" + }, + { + "command": "vote removeRole", + "parameters": [ + "role" + ], + "description": "Removes a role to the list of roles the vote will be sent to" + }, + { + "command": "vote setChair", + "parameters": [ + "chair" + ], + "description": "Sets the chair of a voteIf no chair defaults to sending the message to the channel the vote is closed in" + }, + { + "command": "vote setEndTime", + "parameters": [ + "time_string" + ], + "description": "Sets a specific time for the vote to end. Results will be sent to the chair or owner if you use this, not a channel.If the vote has not been sent by the end time it will close automatically once it is sent.:return:" + }, + { + "command": "vote cancel", + "parameters": [ + "title" + ], + "description": "Cancels a vote you are setting up or have sent" + }, + { + "command": "vote addOption", + "parameters": [ + "option_string" + ], + "description": "Adds an option to the current voteseparate the title and description with a \"+\" e.g. option title+option description" + }, + { + "command": "vote addRole", + "parameters": [ + "role" + ], + "description": "Adds a role to the list of roles the vote will be sent toIf no roles are added, the vote will go to all users in a guild (unless a target voice channel has been set)" + }, + { + "command": "vote cancel", + "parameters": [ + "title" + ], + "description": "Cancels a vote you are setting up or have sent" + }, + { + "command": "vote list", "parameters": [], - "description": "Get a list of filtered words in the server" + "description": "Return a list of all votes you have in this guild.:return:" }, { - "command": "modChannelAdd", - "parameters": ["channelId"], - "description": " Add a mod channel for receiving filtered message information (User, Timestamp, Message) to be sent to" + "command": "vote checkResults", + "parameters": [], + "description": "Checks the results of a vote without closing it" }, { - "command": "modChannelRemove", - "parameters": ["channelId"], - "description": "Remove a mod channel from the server" + "command": "vote close", + "parameters": [], + "description": "Ends a vote, and collects the results" }, { - "command": "modChannelList", + "command": "vote preview", "parameters": [], - "description": "See a list of mod channels in the server" + "description": "Generates a preview of what users will see with the current configuration of the vote" }, { - "command": "ignoreUser", - "parameters": ["userMention"], - "description": "Add a new ignored user for the server. This users' messages will be ignored by the Text Filter" + "command": "vote removeOption", + "parameters": [ + "index" + ], + "description": "Removes an option from a vote based on it's index" }, { - "command": "ignoreChannel", - "parameters": ["channelMention"], - "description": "Add a new ignored channel for the server. Messages in this channel will be ignored by the Text Filter" + "command": "vote removeRole", + "parameters": [ + "role" + ], + "description": "Removes a role to the list of roles the vote will be sent to" }, { - "command": "ignoreList", + "command": "vote send", "parameters": [], - "description": "See a list of ignored users/channels in the server" + "description": "Sends a vote to all users within the restrictions set with the current options added" }, { - "command": "unfilter", - "parameters": ["text"], - "description": "Unfilter a word/string/regex of text that was previously filtered" + "command": "vote setChair", + "parameters": [ + "chair" + ], + "description": "Sets the chair of a voteIf no chair defaults to sending the message to the channel the vote is closed in" }, { - "command": "unignore", - "parameters": ["mention"], - "description": "Unignore a user/channel that was previously set as ignored" + "command": "vote setChannel", + "parameters": [ + "channel" + ], + "description": "Sets the target voice channel of a vote (Users connected to this channel will receive the vote message)If there isn't one set votes will go to all users in a guild (unless target roles have been added)" + }, + { + "command": "vote setEndTime", + "parameters": [ + "time_string" + ], + "description": "Sets a specific time for the vote to end. Results will be sent to the chair or owner if you use this, not a channel.If the vote has not been sent by the end time it will close automatically once it is sent.:return:" + }, + { + "command": "vote create", + "parameters": [ + "title" + ], + "description": "Creates a new vote" + }, + { + "command": "vote", + "parameters": [], + "description": "Use k!vote create to create a vote!" } ] }, { - "name": "TwitchAlert", + "name": "TextFilter", "commands": [ { - "command": "twitchAdd", - "parameters": ["channel_id", "twitch_username", "custom_live_message"], - "description": "Add a Twitch user to a Twitch Alert" + "command": "filterList", + "parameters": [], + "description": "Get a list of filtered words on the current guild.:return:" }, { - "command": "twitchRemove", - "parameters": ["channel_id", "twitch_username"], - "description": "Remove a user from a Twitch Alert" + "command": "filterRegex", + "parameters": [ + "regex", + "filter_type", + "too_many_arguments" + ], + "description": "Adds a new regex to the filtered text list:return:" }, { - "command": "twitchAddTeam", - "parameters": ["channel_id", "team_name", "custom_live_message"], - "description": "Add a Twitch team to a Twitch alert" + "command": "filter", + "parameters": [ + "word", + "filter_type", + "too_many_arguments" + ], + "description": "Adds a new word to the filtered text list:return:" }, { - "command": "twitchRemoveTeam", - "parameters": ["channel_id", "team_name"], - "description": "Edit the default message put in a Twitch Alert Notification" + "command": "ignoreChannel", + "parameters": [ + "channel", + "too_many_arguments" + ], + "description": "Add a new ignored channel to the database:return:" }, { - "command": "twitchEditMsg", - "parameters": ["channel", "default_live_message"], - "description": "Edit the default message put in a Twitch Alert Notification" + "command": "ignoreUser", + "parameters": [ + "user", + "too_many_arguments" + ], + "description": "Add a new ignored user to the database:return:" }, { - "command": "twitchViewMsg", - "parameters": ["channel"], - "description": "Shows the current default message for Twitch Alerts" + "command": "ignoreList", + "parameters": [], + "description": "Get a list all ignored users/channels:return:" }, { - "command": "twitchList", - "parameters": ["channel"], - "description": "Shows all current TwitchAlert users and teams in a channel" - } - ] - }, - { - "name": "Verify", - "commands": [ - { - "command": "verifyAdd", - "parameters": ["suffix", "role"], - "description": "Set up a role and email pair for KoalaBot to verify users with" + "command": "modChannelList", + "parameters": [], + "description": "Get a list of filtered mod channels in the guild:return:" }, { - "command": "verifyRemove", - "parameters": ["suffix", "role"], - "description": "Disable an existing verification listener" + "command": "unignore", + "parameters": [ + "ignore", + "too_many_arguments" + ], + "description": "Remove an ignore from the guild:return:" }, { - "command": "reVerify", - "parameters": ["role"], - "description": "Removes a role from all users who have it and marks them as needing to re-verify before giving it back." + "command": "modChannelRemove", + "parameters": [ + "channel_id", + "too_many_arguments" + ], + "description": "Remove a mod channel from the guild:return:" }, { - "command": "verifyList", - "parameters": ["channelId"], - "description": "List the current verification setup for the server" + "command": "modChannelAdd", + "parameters": [ + "channel_id", + "too_many_arguments" + ], + "description": "Add a mod channel to the current guild:return:" }, { - "command": "verify", - "parameters": ["email"], - "description": "Send to KoalaBot in dms to verify an email with our system" + "command": "unfilter", + "parameters": [ + "word", + "too_many_arguments" + ], + "description": "Remove an existing word/test from the filter list:return:" }, { - "command": "unVerify", - "parameters": ["email"], - "description": "Send to KoalaBot in dms to un-verify an email with our system" + "command": "unignore", + "parameters": [ + "ignore", + "too_many_arguments" + ], + "description": "Remove an ignore from the guild:return:" }, { - "command": "confirm", - "parameters": ["token"], - "description": "Send to KoalaBot in dms to confirm the verification of an email" + "command": "modChannelRemove", + "parameters": [ + "channel_id", + "too_many_arguments" + ], + "description": "Remove a mod channel from the guild:return:" } ] }, { - "name": "Vote", + "name": "ReactForRole (RFR)", "commands": [ { - "command": "vote create", - "parameters": ["title"], - "description": "Creates a new vote" + "command": "rfr", + "parameters": [], + "description": "Group of commands for React for Role (rfr) functionality.:return:" }, { - "command": "vote addRole", - "parameters": ["role"], - "description": "Adds a role to the list of roles the vote will be sent to" + "command": "rfr addRequiredRole", + "parameters": [ + "role_str" + ], + "description": "Adds a role to perms to use rfr functionality in a server, so you can specify that you need, e.g. \"@Student\" tobe able to use rfr functionality in the server. It's server-wide permissions handling however. By default anyonecan use rfr functionality in the server. User needs to have admin perms to use.:return:" }, { - "command": "vote removeRole", - "parameters": ["role"], - "description": "Removes a role to the list of roles the vote will be sent to" + "command": "rfr edit addRoles", + "parameters": [], + "description": " Adds roles to an existing rfr message. User is prompted for rfr message channel ID/name/mention, rfr message ID/ URL, emoji-role combos. Emoji-role combinations are to be given in \\\"<emoji>, <role>\" \\\"<emoji>, <role>\" format. <role> can be the role ID, name or mention. `emoji` can be a custom emoji from the server, or a standard unicode emoji. \\User needs admin perms to use. :param ctx: Context of the command. :return: " }, { - "command": "vote setChair", - "parameters": ["chair_user"], - "description": "Sets the chair of a vote (no chair defaults to message the channel)" + "command": "rfr create", + "parameters": [], + "description": "Creates a new rfr message in a channel of user's choice. User is prompted for (in this order)channel ID/name/mention, message title, message description. Default title and description exist, which are\"React for Role\" and \"Roles below!\" respectively. User requires admin perms to use.:return:" }, { - "command": "vote setChannel", - "parameters": ["channel"], - "description": "Sets the target voice channel of a vote (Users connected to this channel will receive the vote message)" + "command": "rfr delete", + "parameters": [], + "description": "Deletes an existing rfr message. User is prompted for (in this order) channel ID/name/mention, message ID/URL,Y/N confirmation. User needs admin perms to use.:return:" }, { - "command": "vote addOption", - "parameters": ["option"], - "description": "Adds an option to the current vote (separate the title and description with a '+' e.g. option title+option description)" + "command": "rfr edit description", + "parameters": [], + "description": "Edit the description of an existing rfr message. User is prompted for rfr message channel ID/name/mention,rfr message ID/URL, new description, Y/N confirmation. User needs admin perms to use.:return:" }, { - "command": "vote removeOption", - "parameters": ["index"], - "description": "Removes an option from a vote based on it's index" + "command": "rfr edit inline", + "parameters": [], + "description": "Edit the inline property of embed fields in rfr embeds. Can edit all rfr messages in a server or a specific one.User is prompted for whether they'd like inline fields or not, as well as details of the specific message ifthat option is selected. User requires admin perms:return:" }, { - "command": "vote setEndTime", - "parameters": ["time_string"], - "description": "Sets a specific time for the vote to end. Results will be sent to the chair or owner if you use this, not a channel" + "command": "rfr edit thumbnail", + "parameters": [], + "description": "Edit the thumbnail of an existing rfr message. User is prompted for rfr message channel ID/name/mention, rfrmessage ID/URL, new thumbnail, Y/N confirmation. User needs admin perms:return:" }, { - "command": "vote preview", + "command": "rfr edit title", "parameters": [], - "description": "Generates a preview of what users will see with the current configuration of the vote" + "description": "Edit the title of an existing rfr message. User is prompted for rfr message channel ID/name/mention,rfr message ID/URL, new title, Y/N confirmation. User needs admin perms to use.:return:" }, { - "command": "vote cancel", - "parameters": ["title"], - "description": "Cancels a vote you are setting up or have sent" + "command": "rfr edit fixEmbed", + "parameters": [], + "description": "Cosmetic fix method if the bot ever has a moment and doesn't react with the correct emojis/has duplicates." }, { - "command": "vote list", + "command": "rfr listRequiredRoles", "parameters": [], - "description": "Return a list of all votes you have in this server" + "description": "Lists the server-specific role permissions for using rfr functionality. If list is empty, any role can use rfrfunctionality.:return:" }, { - "command": "vote send", + "command": "rfr removeRequiredRole", + "parameters": [ + "role_str" + ], + "description": "Removes a role from perms for use of rfr functionality in a server, so you can specify that you need, e.g.\"@Student\" to be able to use rfr functionality in the server. It's server-wide permissions handling however. Bydefault anyone can use rfr functionality in the server. User needs to have admin perms to use.:return:" + }, + { + "command": "rfr edit removeRoles", "parameters": [], - "description": "Sends a vote to all users within the restrictions set with the current options added" + "description": " Removes roles from an existing rfr message. User is prompted for rfr message channel ID/name/mention, rfr message ID/URL, emojis/roles to remove. User can specify either the emoji or the role for any emoji-role combination to remove it, but it needs to be specified in the format below. \\\"<emoji>/<role>\" \\\"<emoji>/<role>\" <role> can be the role ID, name or mention. emoji can be a custom emoji from the server, or a standard unicode emoji. \\User needs admin perms to use. :param ctx: Context of the command. :return: " + } + ] + }, + { + "name": "ColourRole", + "commands": [ + { + "command": "addCustomColourAllowedRole", + "parameters": [ + "role_str" + ], + "description": "Adds a role, via ID, mention or name, to the list of roles allowed to have a custom colour. Needsadmin permissions to use." }, { - "command": "vote close", - "parameters": ["title"], - "description": "Ends a vote, and collects the results" + "command": "addProtectedRoleColour", + "parameters": [ + "role_str" + ], + "description": "Adds a role, via ID, mention or name, to the list of protected roles. Needs admin permissions touse." }, { - "command": "vote checkResults", - "parameters": ["title"], - "description": "Checks the results of a vote without closing it" + "command": "customColour", + "parameters": [ + "colour_str" + ], + "description": "For a user with the correct role to be able to change their display colour in a guild.Syntax is k!custom_colour (\"no\" / colour hex). Usage with no removes any custom colour held before.Won't accept it if the colour chosen too closely resembles a role that was protected's colour or a discordblocked colour. A role must be made and that role be added to the permissions by usage ofk!add_custom_colour_allowed_role <role>, and the command invoker must have that role before they can use thiscommand. Has a 15 second cooldown." + }, + { + "command": "listCustomColourAllowedRoles", + "parameters": [], + "description": "Lists the roles in a guild which are permitted to have their own custom colours. Requires adminpermissions to use.:return: Sends a message with the mentions of the roles that are protected in a guild." + }, + { + "command": "listProtectedRoleColours", + "parameters": [], + "description": "Lists the protected roles, whose colours are protected from being imitated by a custom colour, in aguild. Requires admin permissions to use.:return: Sends a message with the mentions of the roles that are protected in a guild" + }, + { + "command": "removeCustomColourAllowedRole", + "parameters": [ + "role_str" + ], + "description": "Removes a role, via ID, mention or name, from the list of roles allowed to have a custom colour.Needs admin permissions to use." + }, + { + "command": "removeProtectedRoleColour", + "parameters": [ + "role_str" + ], + "description": "Removes a role, via ID, mention or name, from the list of protected roles. Needs admin permissionsto use." } ] } -] +] \ No newline at end of file diff --git a/tests/TestDocumentation.json b/tests/TestDocumentation.json new file mode 100644 index 00000000..37437000 --- /dev/null +++ b/tests/TestDocumentation.json @@ -0,0 +1,418 @@ +[ + { + "name": "KoalaBot", + "commands": [ + { + "command": "listExt", + "parameters": [], + "description": "Lists all enabled and disabled Koala Extensions on your server" + }, + { + "command": "enableExt", + "parameters": ["koala_extension"], + "description": "Enable a Koala Extension on your server" + }, + { + "command": "disableExt", + "parameters": ["koala_extension"], + "description": "Disable a Koala Extension on your server" + }, + { + "command": "welcomeUpdateMsg", + "parameters": [], + "description": "Change the customisable part of the welcome message of your server" + }, + { + "command": "welcomeSendMsg", + "parameters": [], + "description": "Sends out the welcome message manually to all members of your server" + }, + { + "command": "welcomeViewMsg", + "parameters": [], + "description": "Shows this server's current welcome message" + }, + { + "command": "clear", + "parameters": ["amount"], + "description": "Clears a given number of messages from the channel." + }, + { + "command": "ping", + "parameters": [], + "description": "Returns the ping of a bot" + }, + { + "command": "support", + "parameters": [], + "description": "Returns a link to the KoalaBot Support Discord Server" + } + ] + }, + { + "name": "Announce", + "commands": [ + { + "command": "announce create", + "parameters": [], + "description": "Create a new message that will be available for sending" + }, + { + "command": "changeTitle", + "parameters": [], + "description": "Change the title of the embedded message" + }, + { + "command": "changeContent", + "parameters": [], + "description": "Change the content of the embedded message" + }, + { + "command": "addRole", + "parameters": [], + "description": "Add a role to list of people to send the announcement to" + }, + { + "command": "removeRole", + "parameters": [], + "description": "Remove a role from a list of people to send the announcement to" + }, + { + "command": "preview", + "parameters": [], + "description": "Post a constructed embedded message to the channel where the command is invoked" + }, + { + "command": "send", + "parameters": [], + "description": "Send a pending announcement" + }, + { + "command": "cancel", + "parameters": [], + "description": "Cancel a pending announcement" + } + ] + }, + { + "name": "ColourRole", + "commands": [ + { + "command": "customColour", + "parameters": ["colour_hexcode/'no'"], + "description": "Gives a user a chosen custom colour, or removes the custom colour with 'k!customColour no'" + }, + { + "command": "listProtectedRoleColours", + "parameters": [], + "description": "Lists the protected roles, whose colours are protected from being imitated by a custom colour, in a server" + }, + { + "command": "addProtectedRoleColour", + "parameters": ["role"], + "description": "Adds a role's colour to the list of protected roles" + }, + { + "command": "removeProtectedRoleColour", + "parameters": ["role"], + "description": "Removes a role's colour from the list of protected roles" + }, + { + "command": "listCustomColourAllowedRoles", + "parameters": [], + "description": "Lists the roles in a server whose users are permitted to have their own custom colours" + }, + { + "command": "addCustomColourAllowedRole", + "parameters": ["role"], + "description": "Adds a role to the list of roles allowed to have a custom colour" + }, + { + "command": "removeCustomColourAllowedRole", + "parameters": ["role_str"], + "description": "Removes a role from the list of roles allowed to have a custom colour" + } + ] + }, + { + "name": "ReactForRole (RFR)", + "commands": [ + { + "command": "rfr create", + "parameters": [], + "description": "Create a new, blank rfr message. Default title is React for Role. Default description is Roles below!" + }, + { + "command": "rfr delete", + "parameters": [], + "description": "Delete an existing rfr message" + }, + { + "command": "rfr addRequiredRole", + "parameters": ["role"], + "description": "Add a server-wide role required to react to/use rfr functionality. If no role is added, anyone can use rfr functionality" + }, + { + "command": "rfr removeRequiredRole", + "parameters": ["role"], + "description": "Removes a server-wide role from the group of roles someone requires to use rfr functionality" + }, + { + "command": "rfr listRequiredRoles", + "parameters": [], + "description": "Lists the server-specific role permissions for using rfr functionality" + }, + { + "command": "rfr edit description", + "parameters": [], + "description": "Edit the description of an existing rfr message" + }, + { + "command": "rfr edit title", + "parameters": [], + "description": "Edit the title of an existing rfr message" + }, + { + "command": "rfr edit thumbnail", + "parameters": [], + "description": "Edit the thumbnail of an existing rfr message" + }, + { + "command": "rfr edit inline", + "parameters": [], + "description": "Edit the inline property of embed fields in rfr embeds" + }, + { + "command": "rfr edit addRoles", + "parameters": [], + "description": "Add emoji/role combos to an existing rfr message" + }, + { + "command": "rfr edit removeRoles", + "parameters": [], + "description": "Remove emoji/role combos from an existing rfr message" + }, + { + "command": "rfr edit fixEmbed", + "parameters": [], + "description": "Cosmetic fix method if the bot ever has a moment and doesn't react with the correct emojis/has duplicates" + } + ] + }, + { + "name": "TextFilter", + "commands": [ + { + "command": "filter", + "parameters": ["text", "type"], + "description": "Filter a word or string of text. Type is defaulted to 'banned' which will delete the message and warn the user. Use type 'risky' to just warn the user" + }, + { + "command": "filterRegex", + "parameters": ["regex", "type"], + "description": "Filter a regex string. Type is defaulted to 'banned' which will delete the message and warn the user. Use type 'risky' to just warn the user" + }, + { + "command": "filterList", + "parameters": [], + "description": "Get a list of filtered words in the server" + }, + { + "command": "modChannelAdd", + "parameters": ["channelId"], + "description": " Add a mod channel for receiving filtered message information (User, Timestamp, Message) to be sent to" + }, + { + "command": "modChannelRemove", + "parameters": ["channelId"], + "description": "Remove a mod channel from the server" + }, + { + "command": "modChannelList", + "parameters": [], + "description": "See a list of mod channels in the server" + }, + { + "command": "ignoreUser", + "parameters": ["userMention"], + "description": "Add a new ignored user for the server. This users' messages will be ignored by the Text Filter" + }, + { + "command": "ignoreChannel", + "parameters": ["channelMention"], + "description": "Add a new ignored channel for the server. Messages in this channel will be ignored by the Text Filter" + }, + { + "command": "ignoreList", + "parameters": [], + "description": "See a list of ignored users/channels in the server" + }, + { + "command": "unfilter", + "parameters": ["text"], + "description": "Unfilter a word/string/regex of text that was previously filtered" + }, + { + "command": "unignore", + "parameters": ["mention"], + "description": "Unignore a user/channel that was previously set as ignored" + } + ] + }, + { + "name": "TwitchAlert", + "commands": [ + { + "command": "twitchAdd", + "parameters": ["channel_id", "twitch_username", "custom_live_message"], + "description": "Add a Twitch user to a Twitch Alert" + }, + { + "command": "twitchRemove", + "parameters": ["channel_id", "twitch_username"], + "description": "Remove a user from a Twitch Alert" + }, + { + "command": "twitchAddTeam", + "parameters": ["channel_id", "team_name", "custom_live_message"], + "description": "Add a Twitch team to a Twitch alert" + }, + { + "command": "twitchRemoveTeam", + "parameters": ["channel_id", "team_name"], + "description": "Edit the default message put in a Twitch Alert Notification" + }, + { + "command": "twitchEditMsg", + "parameters": ["channel", "default_live_message"], + "description": "Edit the default message put in a Twitch Alert Notification" + }, + { + "command": "twitchViewMsg", + "parameters": ["channel"], + "description": "Shows the current default message for Twitch Alerts" + }, + { + "command": "twitchList", + "parameters": ["channel"], + "description": "Shows all current TwitchAlert users and teams in a channel" + } + ] + }, + { + "name": "Verify", + "commands": [ + { + "command": "verifyAdd", + "parameters": ["suffix", "role"], + "description": "Set up a role and email pair for KoalaBot to verify users with" + }, + { + "command": "verifyRemove", + "parameters": ["suffix", "role"], + "description": "Disable an existing verification listener" + }, + { + "command": "reVerify", + "parameters": ["role"], + "description": "Removes a role from all users who have it and marks them as needing to re-verify before giving it back." + }, + { + "command": "verifyList", + "parameters": ["channelId"], + "description": "List the current verification setup for the server" + }, + { + "command": "verify", + "parameters": ["email"], + "description": "Send to KoalaBot in dms to verify an email with our system" + }, + { + "command": "unVerify", + "parameters": ["email"], + "description": "Send to KoalaBot in dms to un-verify an email with our system" + }, + { + "command": "confirm", + "parameters": ["token"], + "description": "Send to KoalaBot in dms to confirm the verification of an email" + } + ] + }, + { + "name": "Vote", + "commands": [ + { + "command": "vote create", + "parameters": ["title"], + "description": "Creates a new vote" + }, + { + "command": "vote addRole", + "parameters": ["role"], + "description": "Adds a role to the list of roles the vote will be sent to" + }, + { + "command": "vote removeRole", + "parameters": ["role"], + "description": "Removes a role to the list of roles the vote will be sent to" + }, + { + "command": "vote setChair", + "parameters": ["chair_user"], + "description": "Sets the chair of a vote (no chair defaults to message the channel)" + }, + { + "command": "vote setChannel", + "parameters": ["channel"], + "description": "Sets the target voice channel of a vote (Users connected to this channel will receive the vote message)" + }, + { + "command": "vote addOption", + "parameters": ["option"], + "description": "Adds an option to the current vote (separate the title and description with a '+' e.g. option title+option description)" + }, + { + "command": "vote removeOption", + "parameters": ["index"], + "description": "Removes an option from a vote based on it's index" + }, + { + "command": "vote setEndTime", + "parameters": ["time_string"], + "description": "Sets a specific time for the vote to end. Results will be sent to the chair or owner if you use this, not a channel" + }, + { + "command": "vote preview", + "parameters": [], + "description": "Generates a preview of what users will see with the current configuration of the vote" + }, + { + "command": "vote cancel", + "parameters": ["title"], + "description": "Cancels a vote you are setting up or have sent" + }, + { + "command": "vote list", + "parameters": [], + "description": "Return a list of all votes you have in this server" + }, + { + "command": "vote send", + "parameters": [], + "description": "Sends a vote to all users within the restrictions set with the current options added" + }, + { + "command": "vote close", + "parameters": ["title"], + "description": "Ends a vote, and collects the results" + }, + { + "command": "vote checkResults", + "parameters": ["title"], + "description": "Checks the results of a vote without closing it" + } + ] + } + ] + \ No newline at end of file diff --git a/tests/test_GenerateDoc.py b/tests/test_GenerateDoc.py new file mode 100644 index 00000000..0e518a79 --- /dev/null +++ b/tests/test_GenerateDoc.py @@ -0,0 +1,65 @@ +import pytest +import json +from GenerateDoc import doc_list_to_json, get_cog_docs +from pathlib import Path + +""" +Testing GenerateDoc.py + +Compares automatically generated document to a manually created one +""" + +def open__as_json(filename): + with open(filename) as json_file: + correctDocString = json.load(json_file) + autoDocString = doc_list_to_json(get_cog_docs()) + return correctDocString, autoDocString + +@pytest.mark.parametrize("filename", ['tests/TestDocumentation.json']) +def test_compare_cog_names(filename): + correctDocString, autoDocString = open__as_json(filename) + assert(len(correctDocString) == len(autoDocString)) + names = [doc['name'] for doc in autoDocString] + for doc in correctDocString: + assert doc['name'] in names + + +""" +@pytest.mark.parametrize("filename", ['tests/TestDocumentation.json']) +def test_compare_cog_command(filename): + correctDocString, autoDocString = open__as_json(filename) + assert(len(correctDocString) == len(autoDocString)) + for i in range(0, len(correctDocString)): + for j in range(0, len(correctDocString[i]['commands'])): + assert(correctDocString[i]['commands'][j] == autoDocString[i]['commands'][j]) +""" + +@pytest.mark.parametrize("filename", ['tests/TestDocumentation.json']) +def test_compare_cog_command_name(filename): + correctDocString, autoDocString = open__as_json(filename) + + assert(len(correctDocString) == len(autoDocString)) + for i in range(0, len(correctDocString)): + commandNames = [entry['command'] for entry in autoDocString[i]['commands']] + for command in autoDocString[i]['commands']: + assert(command['command'] in commandNames) + +@pytest.mark.parametrize("filename", ['tests/TestDocumentation.json']) +def test_compare_cog_command_parameters(filename): + correctDocString, autoDocString = open__as_json(filename) + + assert(len(correctDocString) == len(autoDocString)) + for i in range(0, len(correctDocString)): + params = [entry['parameters'] for entry in autoDocString[i]['commands']] + for command in autoDocString[i]['commands']: + assert(command['parameters'] in params) + +@pytest.mark.parametrize("filename", ['tests/TestDocumentation.json']) +def test_compare_cog_command_description(filename): + correctDocString, autoDocString = open__as_json(filename) + + assert(len(correctDocString) == len(autoDocString)) + for i in range(0, len(correctDocString)): + descriptions = [entry['description'] for entry in autoDocString[i]['commands']] + for command in autoDocString[i]['commands']: + assert(command['description'] in descriptions)