From 395c184eefe4d1536912e408d73aa07bdcc82160 Mon Sep 17 00:00:00 2001 From: bobloy Date: Sun, 22 Nov 2020 17:57:11 -0500 Subject: [PATCH] [Docs] Economy Cog Guide (#4519) * Started docstrings * Add to index * First generated guide * Indented examples, some more docstrings * Aliases are now `in ticks and fully qualified` * More economy docstrings * Started docstrings * Add to index * First generated guide * Indented examples, some more docstrings * Aliases are now `in ticks and fully qualified` * More economy docstrings * Regenerate docs * Much more docstrings and regenerate docs * Better explaination of `bank set` and grammar changes * Regenerate docs Co-authored-by: jack1142 <6032823+jack1142@users.noreply.github.com> --- docs/cog_guides/economy.rst | 535 +++++++++++++++++++++++++++++++++ docs/index.rst | 1 + redbot/cogs/economy/economy.py | 190 ++++++++++-- 3 files changed, 703 insertions(+), 23 deletions(-) create mode 100644 docs/cog_guides/economy.rst diff --git a/docs/cog_guides/economy.rst b/docs/cog_guides/economy.rst new file mode 100644 index 000000000..b22520734 --- /dev/null +++ b/docs/cog_guides/economy.rst @@ -0,0 +1,535 @@ +.. _economy: + +======= +Economy +======= + +This is the cog guide for the economy cog. You will +find detailed docs about usage and commands. + +``[p]`` is considered as your prefix. + +.. note:: To use this cog, load it by typing this:: + + [p]load economy + +.. _economy-usage: + +----- +Usage +----- + +Get rich and have fun with imaginary currency! + + +.. _economy-commands: + +-------- +Commands +-------- + +.. _economy-command-bank: + +^^^^ +bank +^^^^ + +**Syntax** + +.. code-block:: none + + [p]bank + +**Description** + +Base command to manage the bank. + +.. _economy-command-bank-balance: + +"""""""""""" +bank balance +"""""""""""" + +**Syntax** + +.. code-block:: none + + [p]bank balance [user] + +**Description** + +Show the user's account balance. + +Example: + - ``[p]bank balance`` + - ``[p]bank balance @Twentysix`` + +**Arguments** + +- ```` The user to check the balance of. If omitted, defaults to your own balance. + +.. _economy-command-bank-prune: + +"""""""""" +bank prune +"""""""""" + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]bank prune + +**Description** + +Base command for pruning bank accounts. + +.. _economy-command-bank-prune-global: + +""""""""""""""""" +bank prune global +""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]bank prune global [confirmation=False] + +**Description** + +Prune bank accounts for users who no longer share a server with the bot. + +Cannot be used without a global bank. See ``[p]bank prune server``. + +Examples: + - ``[p]bank prune global`` - Did not confirm. Shows the help message. + - ``[p]bank prune global yes`` + +**Arguments** + +- ```` This will default to false unless specified. + +.. _economy-command-bank-prune-server: + +""""""""""""""""" +bank prune server +""""""""""""""""" + +.. note:: |guildowner-lock| + +**Syntax** + +.. code-block:: none + + [p]bank prune server [confirmation=False] + +.. tip:: Aliases: ``bank prune guild``, ``bank prune local`` + +**Description** + +Prune bank accounts for users no longer in the server. + +Cannot be used with a global bank. See ``[p]bank prune global``. + +Examples: + - ``[p]bank prune server`` - Did not confirm. Shows the help message. + - ``[p]bank prune server yes`` + +**Arguments** + +- ```` This will default to false unless specified. + +.. _economy-command-bank-prune-user: + +""""""""""""""" +bank prune user +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]bank prune user [confirmation=False] + +**Description** + +Delete the bank account of a specified user. + +Examples: + - ``[p]bank prune user @TwentySix`` - Did not confirm. Shows the help message. + - ``[p]bank prune user @TwentySix yes`` + +**Arguments** + +- ```` The user to delete the bank of. Takes mentions, names, and user ids. +- ```` This will default to false unless specified. + +.. _economy-command-bank-reset: + +"""""""""" +bank reset +"""""""""" + +.. note:: |guildowner-lock| + +**Syntax** + +.. code-block:: none + + [p]bank reset [confirmation=False] + +**Description** + +Delete all bank accounts. + +Examples: + - ``[p]bank reset`` - Did not confirm. Shows the help message. + - ``[p]bank reset yes`` + +**Arguments** + +- ```` This will default to false unless specified. + +.. _economy-command-bank-set: + +"""""""" +bank set +"""""""" + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]bank set + +**Description** + +Set the balance of a user's bank account. + +Putting + or - signs before the amount will add/remove currency on the user's bank account instead. + +Examples: + - ``[p]bank set @Twentysix 26`` - Sets balance to 26 + - ``[p]bank set @Twentysix +2`` - Increases balance by 2 + - ``[p]bank set @Twentysix -6`` - Decreases balance by 6 + +**Arguments** + +- ```` The user to set the currency of. +- ```` The amount of currency to set their balance to. + +.. _economy-command-bank-transfer: + +""""""""""""" +bank transfer +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]bank transfer + +**Description** + +Transfer currency to other users. + +This will come out of your balance, so make sure you have enough. + +Example: + - ``[p]bank transfer @Twentysix 500`` + +**Arguments** + +- ```` The user to give currency to. +- ```` The amount of currency to give. + +.. _economy-command-economyset: + +^^^^^^^^^^ +economyset +^^^^^^^^^^ + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]economyset + +**Description** + +Base command to manage Economy settings. + +.. _economy-command-economyset-paydayamount: + +""""""""""""""""""""""" +economyset paydayamount +""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]economyset paydayamount + +**Description** + +Set the amount earned each payday. + +Example: + - ``[p]economyset paydayamount 400`` + +**Arguments** + +- ```` The new amount to give when using the payday command. Default is 120. + +.. _economy-command-economyset-paydaytime: + +""""""""""""""""""""" +economyset paydaytime +""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]economyset paydaytime + +**Description** + +Set the cooldown for the payday command. + +Example: + - ``[p]economyset paydaytime 86400`` + +**Arguments** + +- ```` The new number of seconds to wait in between uses of payday. Default is 300. + +.. _economy-command-economyset-registeramount: + +""""""""""""""""""""""""" +economyset registeramount +""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]economyset registeramount + +**Description** + +Set the initial balance for new bank accounts. + +Example: + - ``[p]economyset registeramount 5000`` + +**Arguments** + +- ```` The new initial balance amount. Default is 0. + +.. _economy-command-economyset-rolepaydayamount: + +""""""""""""""""""""""""""" +economyset rolepaydayamount +""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]economyset rolepaydayamount + +**Description** + +Set the amount earned each payday for a role. + +Only available when not using a global bank. + +Example: + - ``[p]economyset rolepaydayamount @Members 400`` + +**Arguments** + +- ```` The role to assign a custom payday amount to. +- ```` The new amount to give when using the payday command. + +.. _economy-command-economyset-showsettings: + +""""""""""""""""""""""" +economyset showsettings +""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]economyset showsettings + +**Description** + +Shows the current economy settings + +.. _economy-command-economyset-slotmax: + +"""""""""""""""""" +economyset slotmax +"""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]economyset slotmax + +**Description** + +Set the maximum slot machine bid. + +Example: + - ``[p]economyset slotmax 50`` + +**Arguments** + +- ```` The new maximum bid for using the slot machine. Default is 100. + +.. _economy-command-economyset-slotmin: + +"""""""""""""""""" +economyset slotmin +"""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]economyset slotmin + +**Description** + +Set the minimum slot machine bid. + +Example: + - ``[p]economyset slotmin 10`` + +**Arguments** + +- ```` The new minimum bid for using the slot machine. Default is 5. + +.. _economy-command-economyset-slottime: + +""""""""""""""""""" +economyset slottime +""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]economyset slottime + +**Description** + +Set the cooldown for the slot machine. + +Example: + - ``[p]economyset slottime 10`` + +**Arguments** + +- ```` The new number of seconds to wait in between uses of the slot machine. Default is 5. + +.. _economy-command-leaderboard: + +^^^^^^^^^^^ +leaderboard +^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]leaderboard [top=10] [show_global=False] + +**Description** + +Print the leaderboard. + +Defaults to top 10. + +Examples: + - ``[p]leaderboard`` + - ``[p]leaderboard 50`` - Shows the top 50 instead of top 10. + - ``[p]leaderboard 100 yes`` - Shows the top 100 from all servers. + +**Arguments** + +- ```` How many positions on the leaderboard to show. Defaults to 10 if omitted. +- ```` Whether to include results from all servers. This will default to false unless specified. + +.. _economy-command-payday: + +^^^^^^ +payday +^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]payday + +**Description** + +Get some free currency. + +The amount awarded and frequency can be configured. + +.. _economy-command-payouts: + +^^^^^^^ +payouts +^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]payouts + +**Description** + +Show the payouts for the slot machine. + +.. _economy-command-slot: + +^^^^ +slot +^^^^ + +**Syntax** + +.. code-block:: none + + [p]slot + +**Description** + +Use the slot machine. + +Example: + - ``[p]slot 50`` + +**Arguments** + +- ```` The amount to bet on the slot machine. Winning payouts are higher when you bet more. diff --git a/docs/index.rst b/docs/index.rst index 1e7ba21db..64ca498ae 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,6 +39,7 @@ Welcome to Red - Discord Bot's documentation! cog_guides/cog_manager_ui cog_guides/customcommands cog_guides/downloader + cog_guides/economy red_core_data_statement .. toctree:: diff --git a/redbot/cogs/economy/economy.py b/redbot/cogs/economy/economy.py index bbecab963..e4d260259 100644 --- a/redbot/cogs/economy/economy.py +++ b/redbot/cogs/economy/economy.py @@ -167,14 +167,21 @@ class Economy(commands.Cog): @guild_only_check() @commands.group(name="bank") async def _bank(self, ctx: commands.Context): - """Manage the bank.""" + """Base command to manage the bank.""" pass @_bank.command() async def balance(self, ctx: commands.Context, user: discord.Member = None): """Show the user's account balance. - Defaults to yours.""" + Example: + - `[p]bank balance` + - `[p]bank balance @Twentysix` + + **Arguments** + + - `` The user to check the balance of. If omitted, defaults to your own balance. + """ if user is None: user = ctx.author @@ -192,7 +199,18 @@ class Economy(commands.Cog): @_bank.command() async def transfer(self, ctx: commands.Context, to: discord.Member, amount: int): - """Transfer currency to other users.""" + """Transfer currency to other users. + + This will come out of your balance, so make sure you have enough. + + Example: + - `[p]bank transfer @Twentysix 500` + + **Arguments** + + - `` The user to give currency to. + - `` The amount of currency to give. + """ from_ = ctx.author currency = await bank.get_currency_name(ctx.guild) @@ -214,14 +232,19 @@ class Economy(commands.Cog): @checks.admin_or_permissions(manage_guild=True) @_bank.command(name="set") async def _set(self, ctx: commands.Context, to: discord.Member, creds: SetParser): - """Set the balance of user's bank account. + """Set the balance of a user's bank account. - Passing positive and negative values will add/remove currency instead. + Putting + or - signs before the amount will add/remove currency on the user's bank account instead. Examples: - - `[p]bank set @Twentysix 26` - Sets balance to 26 - - `[p]bank set @Twentysix +2` - Increases balance by 2 - - `[p]bank set @Twentysix -6` - Decreases balance by 6 + - `[p]bank set @Twentysix 26` - Sets balance to 26 + - `[p]bank set @Twentysix +2` - Increases balance by 2 + - `[p]bank set @Twentysix -6` - Decreases balance by 6 + + **Arguments** + + - `` The user to set the currency of. + - `` The amount of currency to set their balance to. """ author = ctx.author currency = await bank.get_currency_name(ctx.guild) @@ -260,7 +283,16 @@ class Economy(commands.Cog): @checks.guildowner_or_permissions(administrator=True) @_bank.command() async def reset(self, ctx, confirmation: bool = False): - """Delete all bank accounts.""" + """Delete all bank accounts. + + Examples: + - `[p]bank reset` - Did not confirm. Shows the help message. + - `[p]bank reset yes` + + **Arguments** + + - `` This will default to false unless specified. + """ if confirmation is False: await ctx.send( _( @@ -283,14 +315,25 @@ class Economy(commands.Cog): @checks.admin_or_permissions(manage_guild=True) @_bank.group(name="prune") async def _prune(self, ctx): - """Prune bank accounts.""" + """Base command for pruning bank accounts.""" pass @_prune.command(name="server", aliases=["guild", "local"]) @commands.guild_only() @checks.guildowner() async def _local(self, ctx, confirmation: bool = False): - """Prune bank accounts for users no longer in the server.""" + """Prune bank accounts for users no longer in the server. + + Cannot be used with a global bank. See `[p]bank prune global`. + + Examples: + - `[p]bank prune server` - Did not confirm. Shows the help message. + - `[p]bank prune server yes` + + **Arguments** + + - `` This will default to false unless specified. + """ global_bank = await bank.is_global() if global_bank is True: return await ctx.send(_("This command cannot be used with a global bank.")) @@ -312,7 +355,18 @@ class Economy(commands.Cog): @_prune.command(name="global") @checks.is_owner() async def _global(self, ctx, confirmation: bool = False): - """Prune bank accounts for users who no longer share a server with the bot.""" + """Prune bank accounts for users who no longer share a server with the bot. + + Cannot be used without a global bank. See `[p]bank prune server`. + + Examples: + - `[p]bank prune global` - Did not confirm. Shows the help message. + - `[p]bank prune global yes` + + **Arguments** + + - `` This will default to false unless specified. + """ global_bank = await bank.is_global() if global_bank is False: return await ctx.send(_("This command cannot be used with a local bank.")) @@ -338,7 +392,17 @@ class Economy(commands.Cog): async def user( self, ctx, member_or_id: Union[discord.Member, RawUserIds], confirmation: bool = False ): - """Delete the bank account of a specified user.""" + """Delete the bank account of a specified user. + + Examples: + - `[p]bank prune user @TwentySix` - Did not confirm. Shows the help message. + - `[p]bank prune user @TwentySix yes` + + **Arguments** + + - `` The user to delete the bank of. Takes mentions, names, and user ids. + - `` This will default to false unless specified. + """ global_bank = await bank.is_global() if global_bank is False and ctx.guild is None: return await ctx.send(_("This command cannot be used in DMs with a local bank.")) @@ -364,7 +428,10 @@ class Economy(commands.Cog): @guild_only_check() @commands.command() async def payday(self, ctx: commands.Context): - """Get some free currency.""" + """Get some free currency. + + The amount awarded and frequency can be configured. + """ author = ctx.author guild = ctx.guild @@ -480,6 +547,16 @@ class Economy(commands.Cog): """Print the leaderboard. Defaults to top 10. + + Examples: + - `[p]leaderboard` + - `[p]leaderboard 50` - Shows the top 50 instead of top 10. + - `[p]leaderboard 100 yes` - Shows the top 100 from all servers. + + **Arguments** + + - `` How many positions on the leaderboard to show. Defaults to 10 if omitted. + - `` Whether to include results from all servers. This will default to false unless specified. """ guild = ctx.guild author = ctx.author @@ -596,7 +673,15 @@ class Economy(commands.Cog): @commands.command() @guild_only_check() async def slot(self, ctx: commands.Context, bid: int): - """Use the slot machine.""" + """Use the slot machine. + + Example: + - `[p]slot 50` + + **Arguments** + + - `` The amount to bet on the slot machine. Winning payouts are higher when you bet more. + """ author = ctx.author guild = ctx.guild channel = ctx.channel @@ -713,7 +798,7 @@ class Economy(commands.Cog): @checks.admin_or_permissions(manage_guild=True) @commands.group() async def economyset(self, ctx: commands.Context): - """Manage Economy settings.""" + """Base command to manage Economy settings.""" @economyset.command(name="showsettings") async def economyset_showsettings(self, ctx: commands.Context): @@ -750,7 +835,15 @@ class Economy(commands.Cog): @economyset.command() async def slotmin(self, ctx: commands.Context, bid: int): - """Set the minimum slot machine bid.""" + """Set the minimum slot machine bid. + + Example: + - `[p]economyset slotmin 10` + + **Arguments** + + - `` The new minimum bid for using the slot machine. Default is 5. + """ if bid < 1: await ctx.send(_("Invalid min bid amount.")) return @@ -768,7 +861,15 @@ class Economy(commands.Cog): @economyset.command() async def slotmax(self, ctx: commands.Context, bid: int): - """Set the maximum slot machine bid.""" + """Set the maximum slot machine bid. + + Example: + - `[p]economyset slotmax 50` + + **Arguments** + + - `` The new maximum bid for using the slot machine. Default is 100. + """ slot_min = await self.config.SLOT_MIN() if bid < 1 or bid < slot_min: await ctx.send( @@ -789,7 +890,15 @@ class Economy(commands.Cog): @economyset.command() async def slottime(self, ctx: commands.Context, seconds: int): - """Set the cooldown for the slot machine.""" + """Set the cooldown for the slot machine. + + Example: + - `[p]economyset slottime 10` + + **Arguments** + + - `` The new number of seconds to wait in between uses of the slot machine. Default is 5. + """ guild = ctx.guild if await bank.is_global(): await self.config.SLOT_TIME.set(seconds) @@ -799,7 +908,15 @@ class Economy(commands.Cog): @economyset.command() async def paydaytime(self, ctx: commands.Context, seconds: int): - """Set the cooldown for payday.""" + """Set the cooldown for the payday command. + + Example: + - `[p]economyset paydaytime 86400` + + **Arguments** + + - `` The new number of seconds to wait in between uses of payday. Default is 300. + """ guild = ctx.guild if await bank.is_global(): await self.config.PAYDAY_TIME.set(seconds) @@ -813,7 +930,15 @@ class Economy(commands.Cog): @economyset.command() async def paydayamount(self, ctx: commands.Context, creds: int): - """Set the amount earned each payday.""" + """Set the amount earned each payday. + + Example: + - `[p]economyset paydayamount 400` + + **Arguments** + + - `` The new amount to give when using the payday command. Default is 120. + """ guild = ctx.guild max_balance = await bank.get_max_balance(ctx.guild) if creds <= 0 or creds > max_balance: @@ -835,7 +960,18 @@ class Economy(commands.Cog): @economyset.command() async def rolepaydayamount(self, ctx: commands.Context, role: discord.Role, creds: int): - """Set the amount earned each payday for a role.""" + """Set the amount earned each payday for a role. + + Only available when not using a global bank. + + Example: + - `[p]economyset rolepaydayamount @Members 400` + + **Arguments** + + - `` The role to assign a custom payday amount to. + - `` The new amount to give when using the payday command. + """ guild = ctx.guild max_balance = await bank.get_max_balance(ctx.guild) if creds <= 0 or creds > max_balance: @@ -858,7 +994,15 @@ class Economy(commands.Cog): @economyset.command() async def registeramount(self, ctx: commands.Context, creds: int): - """Set the initial balance for new bank accounts.""" + """Set the initial balance for new bank accounts. + + Example: + - `[p]economyset registeramount 5000` + + **Arguments** + + - `` The new initial balance amount. Default is 0. + """ guild = ctx.guild max_balance = await bank.get_max_balance(ctx.guild) credits_name = await bank.get_currency_name(guild)