diff --git a/docs/.resources/admin/public_bot.png b/docs/.resources/admin/public_bot.png new file mode 100644 index 000000000..c16080c11 Binary files /dev/null and b/docs/.resources/admin/public_bot.png differ diff --git a/docs/cog_guides/admin.rst b/docs/cog_guides/admin.rst new file mode 100644 index 000000000..9c0a02d35 --- /dev/null +++ b/docs/cog_guides/admin.rst @@ -0,0 +1,435 @@ +.. _admin: + +===== +Admin +===== + +This is the cog guide for the admin 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 admin + +.. _admin-usage: + +----- +Usage +----- + +This cog will provide tools for server admins and bot owners. + +It can add or remove a role to a member, edit one or make some available +for members so they can self-assign them as they wish. + +It also provides tools for the bot owner such as server locking (once enabled, +the bot will instantly leave new servers she joins) and announcements, which +will send something in all the servers of the bot. + +.. _admin-commands: + +-------- +Commands +-------- + +Here's a list of all commands available for this cog. + +.. _admin-command-selfrole: + +^^^^^^^^ +selfrole +^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]selfrole + +**Description** + +Add or remove roles to yourself. Those roles must have been configured as user +settable by admins using the :ref:`selfroleset command +`. + +.. _admin-command-selfrole-add: + +"""""""""""" +selfrole add +"""""""""""" + +**Syntax** + +.. code-block:: none + + [p]selfrole add + +**Description** + +Add a role to yourself. It must have been configured as user settable +by admins using the :ref:`selfroleset command `. + +**Arguments** + +* ````: The role you want to attribute to yourself. |role-input| + +.. _admin-command-selfrole-remove: + +""""""""""""""" +selfrole remove +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]selfrole remove + +**Description** + +Remove a role from yourself. It must have been configured as user settable +by admins using the :ref:`selfroleset command `. + +**Arguments** + +* ````: The role you want to remove from yourself. |role-input| + + +.. _admin-command-selfrole-list: + +""""""""""""" +selfrole list +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]selfrole list + +**Description** + +List all of the available roles you can assign to yourself. + +.. _admin-command-selfroleset: + +^^^^^^^^^^^ +selfroleset +^^^^^^^^^^^ + +.. note:: |admin-lock| This is also usable by the members with the + ``Manage roles`` permission. + +**Syntax** + +.. code-block:: none + + [p]selfroleset + +**Description** + +Define the list of user settable roles. Those roles will be available to any +member using the :ref:`selfrole command `. + +.. _admin-command-selfroleset-add: + +""""""""""""""" +selfroleset add +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]selfroleset add + +**Description** + +Add a role to the list of selfroles. + +.. warning:: Members will be able to assign themselves the role. + Make sure it doesn't give extra perms or anything that can break + your server's security. + +**Arguments** + +* ````: The role to add to the list. |role-input| + +.. _admin-command-selfroleset-remove: + +"""""""""""""""""" +selfroleset remove +"""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]selfroleset remove + +**Description** + +Removes a role from the list of selfroles. + +**Arguments** + +* ````: The role to remove from the list. |role-input| + +.. _admin-command-addrole: + +^^^^^^^ +addrole +^^^^^^^ + +.. note:: |admin-lock| This is also usable by the members with the ``Manage + roles`` permission. + +**Syntax** + +.. code-block:: none + + [p]addrole [user] + +**Description** + +Adds a role to a member. If ``user`` is not given, it will be considered +as yourself, the command author. + +**Arguments** + +* ````: The role to add to the member. |role-input-quotes| + +* ``[user]``: The member you want to add the role to. Defaults to the + command author. |member-input| + +.. _admin-command-removerole: + +^^^^^^^^^^ +removerole +^^^^^^^^^^ + +.. note:: |admin-lock| This is also usable by the members with the + ``Manage roles`` permission. + +**Syntax** + +.. code-block:: none + + [p]removerole [user] + +**Description** + +Removes a role from a member. If ``user`` is not given, it will be considered +as yourself, the command author. + +**Arguments** + +* ````: The role to remove. |role-input-quotes| + +* ``[user]``: The member to remove the role from. |member-input| Defaults + to the command author. + +.. _admin-command-editrole: + +^^^^^^^^ +editrole +^^^^^^^^ + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]editrole + +**Description** + +Edits the settings of a role. + +.. _admin-command-editrole-name: + +""""""""""""" +editrole name +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]editrole name + +**Description** + +Edits the name of a role. + +**Arguments** + +* ````: The role name to edit. |role-input-quotes| + +* ````: The new role name. If it has spaces, you must use quotes. + +.. _admin-command-editrole-color: + +"""""""""""""" +editrole color +"""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]editrole color + +**Description** + +Edits the color of a role. + +**Arguments** + +* ````: The role name to edit. |role-input-quotes| + +* ````: The new color to assign. |color-input| + +**Examples** + +* ``[p]editrole color "My role" #ff0000`` + +* ``[p]editrole color "My role" dark_blue`` + +.. _admin-command-announce: + +^^^^^^^^ +announce +^^^^^^^^ + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]announce + +**Description** + +Announce your message to all of the servers the bot is in. + +The bot will announce the message in the guild's announcements channel. +If this channel is not set, the message won't be announced. + +**Arguments** + +* ````: The message to send. + +.. _admin-command-announce-cancel: + +""""""""""""""" +announce cancel +""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]announce cancel + +**Description** + +Cancels an active announcement. + +.. _admin-command-announceset: + +^^^^^^^^^^^ +announceset +^^^^^^^^^^^ + +.. note:: |guildowner-lock| + +**Syntax** + +.. code-block:: none + + [p]announceset + +**Description** + +Change how announcements are received in this guild. + +.. _admin-command-announceset-channel: + +""""""""""""""""""" +announceset channel +""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]announceset channel [channel] + +**Description** + +Sets the channel where the bot owner announcements will be sent. + +**Arguments** + +* ``[channel]``: The channel that will be used for bot announcements. + |channel-input| Defaults to where you typed the command. + +.. _admin-command-announceset-clearchannel: + +"""""""""""""""""""""""" +announceset clearchannel +"""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]announceset clearchannel + +**Description** + +Disables announcements on your server. To enable them again, you will have to +re-enter your announcements channel with the :ref:`announceset channel +` command. + +.. _admin-command-serverlock: + +^^^^^^^^^^ +serverlock +^^^^^^^^^^ + +.. note:: |owner-lock| This is also usable by the members with the + ``Administrator`` permission. + +**Syntax** + +.. code-block:: none + + [p]serverlock + +**Description** + +Lock a bot to its current servers only. + +This means that, once you enable this, if someone invites the bot to a new +server, the bot will automatically leave the server. + +.. tip:: Another way to prevent your bot from being invited on more servers is + making it private directly from the developer portal. + + Once a bot is private, it can only be invited by its owner (or team + owners). Other users will get an error on Discord's webpage explaining that + the bot is private. + + To do this, go to the `Discord developer portal + `_, select your application, click "Bot" in + the sidebar, then untick "Public bot". + + .. image:: ../.resources/admin/public_bot.png diff --git a/docs/index.rst b/docs/index.rst index e8e41f5a8..3baf239d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,6 +31,7 @@ Welcome to Red - Discord Bot's documentation! :caption: User guides: getting_started + cog_guides/admin cog_guides/bank red_core_data_statement diff --git a/docs/prolog.txt b/docs/prolog.txt index 3b75c347a..bde59dc2e 100644 --- a/docs/prolog.txt +++ b/docs/prolog.txt @@ -22,20 +22,29 @@ .. This is for describing how a format should be formatted -.. |quotes| replace:: enclosed in quotes if there are spaces - .. |role-input| replace:: Please give **the exact role name or ID**, or it won't be detected. + +.. |role-input-quotes| replace:: Please give **the exact role name or ID**, or it won't be detected. If the role name has spaces, provide it enclosed in quotes like this: ``"my role with spaces"`` .. |member-input| replace:: You can either mention the member, provide its ID, its exact name with - the tag or not, or its nickname (|quotes|). + the tag or not, or its nickname. + +.. |member-input-quotes| replace:: You can either mention the member, provide its ID, its exact + name with the tag or not, or its nickname enclosed in quotes if there are spaces. .. |user-input| replace:: You can either provide the member's ID or its exact name with the tag or - not (|quotes|). + not. + +.. |user-input-quotes| replace:: You can either provide the member's ID or its exact name with the + tag or not, enclosed in quotes if there are spaces. .. |channel-input| replace:: You can either mention the channel, provide its exact name or its ID. -.. |vc-input| replace:: You can either provide the voice channel's ID or its exact name, |quotes|. +.. |vc-input| replace:: You can either provide the voice channel's ID or its exact name. + +.. |vc-input-quotes| replace:: You can either provide the voice channel's ID or its exact name, + enclosed in quotes if there are spaces. .. |color-input| replace:: You can either provide the hexadecimal code of the color, or one of the colors listed here: :class:`discord.Color`.