Add a help command and documentation

[Elsklivet]

For the bot to be more easily used by future ResLife staff, there should be some documentation that explains the specifics of command usage, what each command expects, what could break if the bot does not find what it expects to find, the intended usage/intended order of operations, and so on.

I recommend both markdown or HTML documentation (maybe we could use Doxygen and python's existing docstrings? just an idea) a slash command titled help that will be given an argument that is an Option given a choices parameter of all of the bot's slash commands as well as any other common topics. When a command or topic is selected, the bot will return an embed explaining parameters, usage restrictions, expectations, and operations done by the selected command, or, in the case of a topic, an embed explaining usage and expectations for that topic.

To keep the already-long bot.py file clean, I recommend that the details for each command or topic are stored outside of bot.py and loaded in. This could be achieved by making a docs/ directory, in which there would be the HTML/Markdown documentation as well as either a topics.py or topics.json/topics.yml/topics.toml (any easily parseable object format; I personally think JSON would be simplest since orjson module is already loaded by the bot, but YAML is more readable in my opinion).

In the case of using topics.py, the file would consist of a base Python class like Topic or HelpTopic that contains all of the possible attributes that would be sent in the embed (therefore, it is important that it contains something like parameters, even if not all topics will have them) and another Python class for each possible help topic that extends the Topic class and contains information specific to that topic. This way, when the help command is run, it just needs to fetch the appropriate class for whichever topic was selected and use that to build an embed based on which attributes are or are not present like:

# Is a permissions attribute actually set for this object?
if TopicObject.permissions:
    embed.add_field(name="Permissions Required", value=TopicObject.permissions)

# Are parameters actually set for this object?
if TopicObject.parameters:
    for parameter in TopicObject.parameters:
         embed.add_field(name=f"Param: {parameter.name}", value=parameter.description, inline=True)

This means that the code for building the embed only has to be written once, instead of being rewritten for every single possible help topic. Object-oriented programming concepts to the rescue!

In the case of using an object format like JSON, the same idea applies, but instead of a topics.py with classes, an object file formatted like so would be present:

"make_categories": {
    "parameters": [
        "link": "URL to raw hastebin or pastebin page including a list of all RAs to build categories for, formatted 'lastname firstname' on each line"
    ],
    "permissions": "Administrator permission required",
    ...
},
"help": {
    "parameters": [ 
         ...

or, in YAML,

make_categories:
  parameters:
    - link: URL to raw hastebin or pastebin page including a list of all RAs to build categories for, formatted 'lastname firstname' on each line
  permissions: Administrator permission required
help:
  parameters:
    - ...

The HTML or Markdown documentation could quite possibly be generated automatically using the same object files if a format like JSON or YAML is used, as many programs and plugins exist to automatically generate documentation from JSON/YAML.

Note that this help command is distinct from the FAQ system proposed in #4 because the FAQ system pertains to ResLife frequently asked questions, not questions about this bot.

Again, I personally recommend both static documentation as well as the command. Having the slash command means that staff can quickly look up help for a topic they need to use without ever having to leave the context of discord. Having the static documentation means that staff can read up on (potentially) more detailed usages and explanations before semesters start so they are comfortable with the bot before it needs to be redeployed by them.

Rough Checklist

• [x] Create docs/ directory
• [x] Make a topics.py or (preferably) topics.json/topics.yml
• [ ] Make a /help slash command that takes an option of all documented commands and topics
  • [ ] Have this command build and respond (ephemerally) with an embed that consists of the attributes parsed from the topics object for the selected topic
• [ ] (Ideally) Generate static HTML or Markdown documentation either directly from the topics.json/topics.yml, from separate object files for each topic, or, in the worst case, by hand.

[blank2121]

so you want a help command that you enter in the name of the command and it tells you about the command like permissions, options, etc.

My question is do you have a specific request for how the info is formatted? like do you want the title to be the name of the command? do you want any info in the footer like who used the help command for example? anything specific like that for the embed?

(just want to day that this is my first time contributing to open source if i go through with this)

[Elsklivet]

My question is do you have a specific request for how the info is formatted? like do you want the title to be the name of the command? do you want any info in the footer like who used the help command for example? anything specific like that for the embed?

I think having the command or topic selected be the embed title makes sense. Who used the help command won't be necessary as responding to discord interactions keeps that information (it looks like replying to a message), and the message should be ephemeral regardless, so no one else will see the response.

Other than that, I think whatever format tends to make sense for the other attributes. They should likely just be embed fields without a lot of glam, because the goal is to write only one layout skeleton and then fill it in based on the object files, so it should be relatively simple. Parameters if any exist, permission requirements, expectations (a role named "residents" exists, a channel named "logs" exists, the user being edited has a role lower than the bot role, etc.), a description, and so on.

[blank2121]

I know you asked for a help command but would you like me to include the context menus as well or no?

---

Also here is how the data looks:

[Elsklivet]

I know you asked for a help command but would you like me to include the context menus as well or no?

Not sure what you mean here by the context menus?

[blank2121]

On line 1348 it says context menu commands and I was wondering if u wanted me to include that.

---

The command is "Reset User"

[Elsklivet]

Ah! I see. Maybe since it is essentially the same command, we could add an embed field like types so that the reset_user help command would have:

    "types": ["Slash Command","User Context Menu"]

and then the embed would have a field that looks like Types Slash Command, User Context Menu

For other commands, it would just be ["Slash Command"] and for topics that are not commands (none I can think of at the moment, so don't worry about those yet) it could just be ["Topic"]

[blank2121]

When I finish do you want me to just send you the code and file or do u want me to do a fork?

[Elsklivet]

When I finish do you want me to just send you the code and file or do u want me to do a fork?

A fork and pull request into the dev branch would be the ideal way to do so.

[blank2121]

i make the pull request! it is all done but it failed a check because of some formatting

[Elsklivet]

No worries, the Deepsource check tends to fail because of formatting.

Requested a couple of minor changes, linking PR here: #45

Note that once #45 is merged, I do not want to close this issue, as there may yet be some documentation to add before the issue is considered completed.