Discord Bot: General Documentation Improvement + more (#813)

* Adding the Discord Bot

From https://github.com/GamestonkTerminal/DiscordBot.

* Fixed code format to GST

* Fixed spelling

* Fixed check errors

* Reformated with pre-commit

* Fixed names of files

* Logging and error output capabilities

Adds logging for the server and displays errors with commands correction to the user.

* Fixed spelling

* Fixed bare exceptions

* Fixed Formating

* Update based on comments

* Fixed arguments for economy & debugging for economy/dps menu

* Fixed default arguments and made them better for debugging and more robust

* DiscordBot: Removes Reactions

Removes reactions from the menu response after given input or timeout.

* Discord Bot: General Improvements

- Fixing an error with the timeout in the pagination command
- Updated README.md to fit the current code structure, installation process and more
- Added documentation to functions of the bot

discordbot/README.md

@@ -35,48 +35,63 @@ Register your app <a href="https://imgur.com/signin?redirect=http://api.imgur.co
 
 Download the code from this repository.
 
-Then open the main.py file and go back to https://discord.com/developers/applications/ and go to your bot page. There you'll have to copy the token
+Then open the config_discordbot.py file and go back to https://discord.com/developers/applications/ and go to your bot page. There you'll have to copy the token
 <img src="images/picture_7.png" alt="Logo" width="1183" height="419">
 
-Then change the settings in the beginning of main.py:
+Then change the settings in the config_discordbot.py. Make sure to add the proper filepath to the GamestonkTerminal folder.
+Add your discord token and imgur id to your environment variables as "GT_DISCORD_BOT_TOKEN" & "GT_IMGUR_CLIENT_ID" or
+change the string in the config. You can also change the command prefix, date format, debug mode and other parameters in the settings
+part of the config file.
+
+From the config_discordbot.py file:
 ```
-##############
-## Settings ##
-##############
-DISCORD_BOT_TOKEN = 'string' # Insert your bots secrets token
-IMGUR_CLIENT_ID = 'string' # Enter your imgur client id
-COMMAND_PREFIX = '!' # Sets the prefix to the commands
-activity = discord.Game(name='Gametonk Terminal: https://github.com/GamestonkTerminal/GamestonkTerminal')
-gst_path = 'C:\\Users\\user\\GamestonkTerminal' # The path to Gamestonk Terminal
-date_input_format = '%Y-%m-%d' # Enter your prefered date input format
+# Path to the terminal
+GST_PATH = os.path.join("~", "Documents", "GamestonkTerminal")
+sys.path.append(GST_PATH)
+
+# https://discord.com/developers/applications/
+DISCORD_BOT_TOKEN = os.getenv("GT_DISCORD_BOT_TOKEN") or "REPLACE_ME"
+
+# https://apidocs.imgur.com
+IMGUR_CLIENT_ID = os.getenv("GT_IMGUR_CLIENT_ID") or "REPLACE_ME"
+
+# Settings
+COMMAND_PREFIX = "!"
+DATE_FORMAT = "%Y-%m-%d"
+COLOR = discord.Color.from_rgb(0, 206, 154)
+MENU_TIMEOUT = 30
+DEBUG = True
+
+AUTHOR_NAME = "Gamestonk Terminal"
+AUTHOR_ICON_URL = (
+    "https://github.com/GamestonkTerminal/GamestonkTerminal/"
+    "blob/main/images/gst_logo_green_white_background.png?raw=true"
+)
 ```
 
 ### Step 3:
-Activate your GST virtual enviroment and go to the place where your main.py file is located and run it.
+Activate your GST virtual environment and go to the place where your main.py file is located and run it.
 <img src="images/image.png" alt="Logo" width="1167" height="294">
-Your finished! Go to your server and you should see the bot online!!!
+You're finished! Go to your server and you should see the bot online!!!
 
 ## Code Structure and Contributing
 The file system is built in the following way:
-- Each context is one file unless it has categories and if it has it then it should have a file in the directory named context_main.py (example: Stocks has as a category Dark Pool Shorts -> stocks is a directory with a file stocks_main.py and dps is a file; economy has no categories -> economy is one file)
-- The settings shall currently be in the main.py file (example: API keys)
+- Each command is one file with the essential functions for the command and is named COMMANDNAME.py.
+- Each context is a directory and has a menu file named CONTEXT_menu.py.
+- The menu file works by controlling every command in the context and it contains the menu command.
+- discordbot.py can loads every menu file from each context.
+- The settings shall be in the config_discordbot.py file (example: API keys).
 
-A context/category file is built in the following way:
-```
-Imports
+If a function is often used by multiple files then add them to the helpers.py file. Please try to use the _view files
+from the GST to get the data for the commands if possible.
 
-Functions
-  Returns the embed or sends the response via pagination function from main
+Feel free to contribute to the discord bot, add more contexts, commands or just do other improvements. To see the
+current prioritize of the development see the TODO list in the discord bot project
+(https://github.com/GamestonkTerminal/GamestonkTerminal/projects/4).
 
-Class with the commands as cogs
-  The Commands call the functions with given arguments
-  Has one command with a list of the commands and can run them via emoji reactions from the user
+## What if something doesn't work?
 
-Add the cogs class to the bot
-```
-If a funtion is often used by a context with categories or multiple files then add them to the context_main.py or the main.py file.
+Make sure to follow the steps in the download guide. If an error occurs anyway then activate the debug mode in the
+config file and see where the error occurs in your terminal. Join the GST discord and report your issue in the #bugs
+channel. Otherwise, there's the possibility to open a GitHub issue or message northern-64bit.
 
-## Disclaimer
-"A few things I am not. I am not a cat. I am not an institutional investor, nor am I a hedge fund. I do not have clients and I do not provide personalized investment advice for fees or commissions." DFV
-
-Trading in financial instruments involves high risks including the risk of losing some, or all, of your investment amount, and may not be suitable for all investors. Before deciding to trade in financial instrument you should be fully informed of the risks and costs associated with trading the financial markets, carefully consider your investment objectives, level of experience, and risk appetite, and seek professional advice where needed. The data contained in GST is not necessarily accurate. GST Discord Bot/GST and any provider of the data contained in this website will not accept liability for any loss or damage as a result of your trading, or your reliance on the information displayed.

discordbot/economy/currencies.py

@@ -5,6 +5,19 @@ from gamestonk_terminal.economy import wsj_model
 
 
 async def currencies_command(ctx, arg=""):
+    """Gets the currencies data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of currencies data to the users
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/economy/economy_menu.py

@@ -58,6 +58,14 @@ class EconomyCommands(discord.ext.commands.Cog):
 
     @discord.ext.commands.command(name="economy")
     async def economy(self, ctx: discord.ext.commands.Context):
+        """Shows Economy Menu
+
+        Returns
+        -------
+        Sends a message to the discord user with the commands from the economy context.
+        The user can then select a reaction to trigger a command.
+        """
+
         if cfg.DEBUG:
             print("!economy")
 

discordbot/economy/feargreed.py

@@ -9,6 +9,19 @@ from gamestonk_terminal.economy import cnn_view, cnn_model
 
 
 async def feargreed_command(ctx, arg=""):
+    """Gets the fear greed data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an image of the fear & greed indicator to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/economy/futures.py

@@ -5,10 +5,23 @@ from gamestonk_terminal.economy import wsj_model
 
 
 async def futures_command(ctx, arg=""):
+    """Gets the futures data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of futures data to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:
-            print(f"!stocks.economy.feargreed {arg}")
+            print(f"!stocks.economy.futures {arg}")
 
         # Help
         if arg == "-h" or arg == "help":

discordbot/economy/glbonds.py

@@ -5,6 +5,19 @@ from gamestonk_terminal.economy import wsj_model
 
 
 async def glbonds_command(ctx, arg=""):
+    """Gets the global bonds data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of global bonds data to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/economy/indices.py

@@ -5,6 +5,19 @@ from gamestonk_terminal.economy import wsj_model
 
 
 async def indices_command(ctx, arg=""):
+    """Gets the indices data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of indices data to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/economy/overview.py

@@ -5,6 +5,19 @@ from gamestonk_terminal.economy import wsj_model
 
 
 async def overview_command(ctx, arg=""):
+    """Gets the market overview data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of market overview data to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/economy/performance.py

@@ -6,6 +6,20 @@ from gamestonk_terminal.economy import finviz_model
 
 
 async def performance_command(ctx, arg="sector"):
+    """Gets the performance data of a entered sector from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        sector (or any other input in the economy_group), -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of the performance data of the given arg
+        with pagination to the user
+    """
+
     economy_group = {
         "sector": "Sector",
         "industry": "Industry",

discordbot/economy/usbonds.py

@@ -5,6 +5,19 @@ from gamestonk_terminal.economy import wsj_model
 
 
 async def usbonds_command(ctx, arg=""):
+    """Gets the US bond data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of US bond data to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/economy/valuation.py

@@ -6,6 +6,20 @@ from gamestonk_terminal.economy import finviz_model
 
 
 async def valuation_command(ctx, arg="sector"):
+    """Gets the valuation data of a entered sector from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        sector (or any other input in the economy_group), -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of the valuation data of the given arg
+        with pagination to the user
+    """
+
     economy_group = {
         "sector": "Sector",
         "industry": "Industry",

discordbot/helpers.py

@@ -85,7 +85,7 @@ async def pagination(cols, ctx):
                         disabled=True,
                     ),
                     discord_components.Button(
-                        label=f"Page {int(cols.index(cols[current])) + 1}/{len(cols)-1}",
+                        label=f"Page {int(cols.index(cols[current]))}/{len(cols)-1}",
                         id="cur",
                         style=discord_components.ButtonStyle.grey,
                         disabled=True,

discordbot/stocks/dark_pool_shorts/dpotc.py

@@ -10,6 +10,20 @@ from gamestonk_terminal.stocks.dark_pool_shorts import finra_model
 
 
 async def dpotc_command(ctx, arg=""):
+    """Displays barchart of dark pool (ATS) and OTC (Non ATS) data and sends it
+
+    Parameters
+    -----------
+    arg: str
+        ticker, -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an image displaying a barchart of dark pool
+        (ATS) and OTC (Non ATS) data to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/stocks/dark_pool_shorts/dps_menu.py

@@ -53,6 +53,14 @@ class DarkPoolShortsCommands(discord.ext.commands.Cog):
 
     @discord.ext.commands.command(name="stocks.dps")
     async def dark_pool_shorts_menu(self, ctx: discord.ext.commands.Context, arg=""):
+        """Shows Economy Menu
+
+        Returns
+        -------
+        Sends a message to the discord user with the commands from the dps context.
+        The user can then select a reaction to trigger a command.
+        """
+
         if cfg.DEBUG:
             print("!stocks.dps")
 

discordbot/stocks/dark_pool_shorts/ftd.py

@@ -11,6 +11,24 @@ from gamestonk_terminal.stocks.dark_pool_shorts import sec_model
 
 
 async def ftd_command(ctx, arg="", arg2="", arg3=""):
+    """Displays barchart of fail of deliver data of a given stock and sends it
+
+    Parameters
+    -----------
+    arg: str
+        ticker, -h or help
+    arg2:
+        date (in date format for start date)
+    arg3:
+        date (in date format for end date)
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an image displaying a barchart fail to
+        deliver data to the user during a given time period
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/stocks/dark_pool_shorts/hsi.py

@@ -6,6 +6,20 @@ from gamestonk_terminal.stocks.dark_pool_shorts import shortinterest_model
 
 
 async def hsi_command(ctx, arg="10"):
+    """Gets high shorted interest data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        number, -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of the stocks with the top high
+        shorted interest to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/stocks/dark_pool_shorts/pos.py

@@ -6,6 +6,22 @@ from gamestonk_terminal.stocks.dark_pool_shorts import stockgrid_model
 
 
 async def pos_command(ctx, arg="dpp_dollar", arg2="10"):
+    """Gets the dark pool shorts data sorted by arg from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        sort (str in dark_pool_short), -h or help
+    arg2: str
+        number
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed of dark pool shorts data given
+        the sorting arg to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/stocks/dark_pool_shorts/psi.py

@@ -10,6 +10,20 @@ from gamestonk_terminal.stocks.dark_pool_shorts import stockgrid_model
 
 
 async def psi_command(ctx, arg=""):
+    """Gets price vs short interest volume plot from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        ticker, -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an image of price vs short interest volume of
+         a given ticker to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/stocks/dark_pool_shorts/shorted.py

@@ -6,6 +6,20 @@ from gamestonk_terminal.stocks.dark_pool_shorts import yahoofinance_model
 
 
 async def shorted_command(ctx, arg="5"):
+    """Gets the most shorted stocks data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        number, -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed containing of the most shorted
+        stocks to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/stocks/dark_pool_shorts/sidtc.py

@@ -6,6 +6,22 @@ from gamestonk_terminal.stocks.dark_pool_shorts import stockgrid_model
 
 
 async def sidtc_command(ctx, arg="float", arg2="10"):
+    """Gets short interest and days to cover data from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        sort (dark_pool_shorts), -h or help
+    arg2: str
+        number
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an embed with short interest and days to cover
+        data to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG:

discordbot/stocks/dark_pool_shorts/spos.py

@@ -9,6 +9,20 @@ from gamestonk_terminal.stocks.dark_pool_shorts import stockgrid_model
 
 
 async def spos_command(ctx, arg=""):
+    """Gets price vs short interest volume plot from GST and sends it
+
+    Parameters
+    -----------
+    arg: str
+        ticker, -h or help
+
+    Returns
+    -------
+    discord message
+        Sends a message containing an image of net short position of a given
+        ticker to the user
+    """
+
     try:
         # Debug
         if cfg.DEBUG: