Merge branch 'V3/develop' into V3/feature/mutes

docs/_templates/layout.html

@@ -0,0 +1,9 @@
+{% extends '!layout.html' %}
+{% block document %}
+{{ super() }}
+<a href="https://github.com/Cog-Creators/Red-DiscordBot">
+    <img style="position: absolute; top: 0; right: 0; border: 0;"
+    src="https://github.blog/wp-content/uploads/2008/12/forkme_right_darkblue_121621.png?resize=149%2C149"
+    class="attachment-full size-full" alt="Fork me on GitHub">
+</a>
+{% endblock %}

docs/autostart_pm2.rst

@@ -17,18 +17,20 @@ Start by installing Node.JS and NPM via your favorite package distributor. From
 After PM2 is installed, run the following command to enable your Red instance to be managed by PM2. Replace the brackets with the required information.
 You can add additional Red based arguments after the instance, such as :code:`--dev`.
 
-:code:`pm2 start redbot --name "<Insert a name here>" --interpreter "<Location to your Python Interpreter>" -- <Red Instance> --no-prompt`
+.. code-block:: none
+
+    pm2 start redbot --name "<Insert a name here>" --interpreter "<Location to your Python Interpreter>" --interpreter-args "-O" -- <Red Instance> --no-prompt
 
 .. code-block:: none
 
     Arguments to replace.
 
-    --name ""
+    <Insert a name here>
     A name to identify the bot within pm2, this is not your Red instance.
 
-    --interpreter ""
-    The location of your Python interpreter, to find out where that is use the following command:
-    which python3.6
+    <Location to your Python Interpreter>
+    The location of your Python interpreter, to find out where that is use the following command inside activated venv:
+    which python
 
     <Red Instance>
     The name of your Red instance.

docs/autostart_systemd.rst

@@ -18,7 +18,7 @@ In order to create the service file, you will first need the location of your :c
     # If you are using pyenv
     pyenv shell <name>
 
-    which redbot
+    which python
 
 Then create the new service file:
 
@@ -33,7 +33,7 @@ Paste the following and replace all instances of :code:`username` with the usern
     After=multi-user.target
 
     [Service]
-    ExecStart=path %I --no-prompt
+    ExecStart=path -O -m redbot %I --no-prompt
     User=username
     Group=username
     Type=idle

docs/changelog_3_2_0.rst

@@ -1,5 +1,68 @@
 .. 3.2.x Changelogs
 
+Redbot 3.2.3 (2020-01-17)
+=========================
+
+Core Bot Changes
+----------------
+
+- Further improvements have been made to bot startup and shutdown.
+- Prefixes are now cached for performance.
+- Added the means for cog creators to use a global preinvoke hook.
+- The bot now ensures it has at least the bare neccessary permissions before running commands.
+- Deleting instances works as intended again.
+- Sinbad stopped fighting it and embraced the entrypoint madness.
+
+Core Commands
+-------------
+
+- The servers command now also shows the ids.
+
+Admin Cog
+---------
+
+- The selfrole command now has reasonable expectations about hierarchy.
+
+Help Formatter
+--------------
+
+- ``[botname]`` is now replaced with the bot's display name in help text.
+- New features added for cog creators to further customize help behavior.
+  
+  - Check out our command reference for details on new ``format_help_for_context`` method.
+- Embed settings are now consistent.
+
+Downloader
+----------
+
+- Improved a few user facing messages.
+- Added pagination of output on cog update.
+- Added logging of failures.
+
+Docs
+----
+
+There's more detail to the below changes, so go read the docs.
+For some reason, documenting documentation changes is hard.
+
+- Added instructions about git version.
+- Clarified instructions for installation and update.
+- Added more details to the API key reference.
+- Fixed some typos and versioning mistakes.
+
+
+Audio
+-----
+
+Draper did things.
+
+- No seriously, Draper did things.
+- Wait you wanted details? Ok, I guess we can share those.
+- Audio properly disconnects with autodisconnect, even if notify is being used.
+- Symbolic links now work as intended for local tracks.
+- Bump play now shows the correct time till next track.
+- Multiple user facing messages have been made more correct.
+
 Redbot 3.2.2 (2020-01-10)
 =========================
 
@@ -49,7 +112,8 @@ Breaking Changes
     - ``bot.get_mod_role_ids`` (`#2967 <https://github.com/Cog-Creators/Red-DiscordBot/issues/2967>`_)
 - Reserved some command names for internal Red use. These are available programatically as ``redbot.core.commands.RESERVED_COMMAND_NAMES``. (`#2973 <https://github.com/Cog-Creators/Red-DiscordBot/issues/2973>`_)
 - Removed ``bot._counter``, Made a few more attrs private (``cog_mgr``, ``main_dir``). (`#2976 <https://github.com/Cog-Creators/Red-DiscordBot/issues/2976>`_)
-- ``bot.wait_until_ready`` should no longer be used during extension setup. (`#3073 <https://github.com/Cog-Creators/Red-DiscordBot/issues/3073>`_)
+- Extension's ``setup()`` function should no longer assume that we are, or even will be connected to Discord.
+  This also means that cog creators should no longer use ``bot.wait_until_ready()`` inside it. (`#3073 <https://github.com/Cog-Creators/Red-DiscordBot/issues/3073>`_)
 - Removed the mongo driver. (`#3099 <https://github.com/Cog-Creators/Red-DiscordBot/issues/3099>`_)
 
 

docs/framework_apikeys.rst

@@ -60,3 +60,16 @@ Event Reference
     :type service_name: :class:`str`
     :param api_tokens: New Mapping of token names to tokens. This contains api tokens that weren't changed too.
     :type api_tokens: Mapping[:class:`str`, :class:`str`]
+
+
+*********************
+Additional References
+*********************
+
+.. py:currentmodule:: redbot.core.bot
+
+.. automethod:: Red.get_shared_api_tokens
+
+.. automethod:: Red.set_shared_api_tokens
+
+.. automethod:: Red.remove_shared_api_tokens

docs/framework_commands.rst

@@ -15,6 +15,7 @@ extend functionlities used throughout the bot, as outlined below.
 
 .. autoclass:: redbot.core.commands.Command
     :members:
+    :inherited-members: format_help_for_context
 
 .. autoclass:: redbot.core.commands.Group
     :members:

docs/framework_modlog.rst

@@ -25,7 +25,7 @@ Basic Usage
         async def ban(self, ctx, user: discord.Member, reason: str = None):
             await ctx.guild.ban(user)
             case = await modlog.create_case(
-                ctx.bot, ctx.guild, ctx.message.created_at, action="ban",
+                ctx.bot, ctx.guild, ctx.message.created_at, action_type="ban",
                 user=user, moderator=ctx.author, reason=reason
             )
             await ctx.send("Done. It was about time.")

docs/install_linux_mac.rst

@@ -19,12 +19,22 @@ Please install the pre-requirements using the commands listed for your operating
 The pre-requirements are:
  - Python 3.8.1 or greater
  - Pip 18.1 or greater
- - Git
+ - Git 2.11+
  - Java Runtime Environment 11 or later (for audio support)
 
 We also recommend installing some basic compiler tools, in case our dependencies don't provide
 pre-built "wheels" for your architecture.
 
+
+*****************
+Operating systems
+*****************
+
+.. contents::
+    :local:
+
+----
+
 .. _install-arch:
 
 ~~~~~~~~~~
@@ -35,6 +45,10 @@ Arch Linux
 
     sudo pacman -Syu python python-pip git jre-openjdk-headless base-devel
 
+Continue by `creating-venv-linux`.
+
+----
+
 .. _install-centos:
 .. _install-rhel:
 
@@ -51,15 +65,44 @@ CentOS and RHEL 7
 
 Complete the rest of the installation by `installing Python 3.8 with pyenv <install-python-pyenv>`.
 
+----
+
+.. _install-debian-stretch:
+
+~~~~~~~~~~~~~~
+Debian Stretch
+~~~~~~~~~~~~~~
+
+.. note::
+
+    This guide is only for Debian Stretch users, these instructions won't work with
+    Raspbian Stretch. Raspbian Buster is the only version of Raspbian supported by Red.
+
+We recommend installing pyenv as a method of installing non-native versions of python on
+Debian Stretch. This guide will tell you how. First, run the following commands:
+
+.. code-block:: none
+
+    sudo echo "deb http://deb.debian.org/debian stretch-backports main" >> /etc/apt/sources.list.d/red-sources.list
+    sudo apt update
+    sudo apt -y install make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
+      libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev \
+      libxmlsec1-dev libffi-dev liblzma-dev libgdbm-dev uuid-dev python3-openssl git openjdk-11-jre
+    CXX=/usr/bin/g++
+
+Complete the rest of the installation by `installing Python 3.8 with pyenv <install-python-pyenv>`.
+
+----
+
 .. _install-debian:
 .. _install-raspbian:
 
-~~~~~~~~~~~~~~~~~~~
-Debian and Raspbian
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Debian and Raspbian Buster
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We recommend installing pyenv as a method of installing non-native versions of python on
-Debian/Raspbian. This guide will tell you how. First, run the following commands:
+Debian/Raspbian Buster. This guide will tell you how. First, run the following commands:
 
 .. code-block:: none
 
@@ -71,6 +114,8 @@ Debian/Raspbian. This guide will tell you how. First, run the following commands
 
 Complete the rest of the installation by `installing Python 3.8 with pyenv <install-python-pyenv>`.
 
+----
+
 .. _install-fedora:
 
 ~~~~~~~~~~~~
@@ -84,6 +129,10 @@ them with dnf:
 
     sudo dnf -y install python38 git java-latest-openjdk-headless @development-tools
 
+Continue by `creating-venv-linux`.
+
+----
+
 .. _install-mac:
 
 ~~~
@@ -110,6 +159,10 @@ one-by-one:
 It's possible you will have network issues. If so, go in your Applications folder, inside it, go in
 the Python 3.8 folder then double click ``Install certificates.command``.
 
+Continue by `creating-venv-linux`.
+
+----
+
 .. _install-opensuse:
 
 ~~~~~~~~
@@ -150,6 +203,8 @@ Now, install pip with easy_install:
 
     sudo /opt/python/bin/easy_install-3.8 pip
 
+Continue by `creating-venv-linux`.
+
 openSUSE Tumbleweed
 *******************
 
@@ -161,35 +216,74 @@ with zypper:
     sudo zypper install python3-base python3-pip git-core java-12-openjdk-headless
     sudo zypper install -t pattern devel_basis
 
+Continue by `creating-venv-linux`.
+
+----
+
 .. _install-ubuntu:
 
-~~~~~~
-Ubuntu
-~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Ubuntu LTS versions (18.04 and 16.04)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note:: **Ubuntu Python Availability**
-
-   We recommend using the deadsnakes ppa to ensure up to date python availability.
-
-    .. code-block:: none
-
-        sudo apt update
-        sudo apt install software-properties-common
-        sudo add-apt-repository ppa:deadsnakes/ppa
-
-Install the pre-requirements with apt:
+We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
 
 .. code-block:: none
 
     sudo apt update
+    sudo apt install software-properties-common
+    sudo add-apt-repository ppa:git-core/ppa
+
+We recommend adding the ``deadsnakes`` ppa to install Python 3.8.1 or greater:
+
+.. code-block:: none
+
+    sudo add-apt-repository ppa:deadsnakes/ppa
+
+Now install the pre-requirements with apt:
+
+.. code-block:: none
+
     sudo apt -y install python3.8 python3.8-dev python3.8-venv python3-pip git default-jre-headless \
       build-essential
 
+Continue by `creating-venv-linux`.
+
+----
+
+.. _install-ubuntu-non-lts:
+
+~~~~~~~~~~~~~~~~~~~~~~~
+Ubuntu non-LTS versions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
+
+.. code-block:: none
+
+    sudo apt update
+    sudo apt install software-properties-common
+    sudo add-apt-repository ppa:git-core/ppa
+
+Now, to install non-native version of python on non-LTS versions of Ubuntu, we recommend
+installing pyenv. To do this, first run the following commands:
+
+.. code-block:: none
+
+    sudo apt -y install make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
+      libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev \
+      libxmlsec1-dev libffi-dev liblzma-dev libgdbm-dev uuid-dev python3-openssl git openjdk-11-jre
+    CXX=/usr/bin/g++
+
+And then complete the rest of the installation by `installing Python 3.8 with pyenv <install-python-pyenv>`.
+
+----
+
 .. _install-python-pyenv:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+****************************
 Installing Python with pyenv
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+****************************
 
 .. note::
 
@@ -227,11 +321,15 @@ After that is finished, run:
 
 Pyenv is now installed and your system should be configured to run Python 3.8.
 
+Continue by `creating-venv-linux`.
+
+.. _creating-venv-linux:
+
 ------------------------------
 Creating a Virtual Environment
 ------------------------------
 
-We **strongly** recommend installing Red into a virtual environment. Don't be scared, it's very
+We require installing Red into a virtual environment. Don't be scared, it's very
 straightforward. See the section `installing-in-virtual-environment`.
 
 .. _installing-red-linux-mac:
@@ -242,31 +340,25 @@ Installing Red
 
 Choose one of the following commands to install Red.
 
-.. note::
-
-    If you're not inside an activated virtual environment, include the ``--user`` flag with all
-    ``python3.8 -m pip install`` commands, like this:
-
-    .. code-block:: none
-
-        python3.8 -m pip install --user -U setuptools wheel
-        python3.8 -m pip install --user -U Red-DiscordBot
-
 To install without additional config backend support:
 
 .. code-block:: none
 
-    python3.8 -m pip install -U setuptools wheel
-    python3.8 -m pip install -U Red-DiscordBot
+    python -m pip install -U pip setuptools wheel
+    python -m pip install -U Red-DiscordBot
 
 Or, to install with PostgreSQL support:
 
 .. code-block:: none
 
-    python3.8 -m pip install -U setuptools wheel
-    python3.8 -m pip install -U Red-DiscordBot[postgres]
+    python -m pip install -U pip setuptools wheel
+    python -m pip install -U Red-DiscordBot[postgres]
 
 
+.. note::
+
+    These commands are also used for updating Red
+
 --------------------------
 Setting Up and Running Red
 --------------------------

docs/install_windows.rst

@@ -64,6 +64,13 @@ Manually installing dependencies
 
 .. _installing-red-windows:
 
+------------------------------
+Creating a Virtual Environment
+------------------------------
+
+We require installing Red into a virtual environment. Don't be scared, it's very
+straightforward. See the section `installing-in-virtual-environment`.
+
 --------------
 Installing Red
 --------------
@@ -72,34 +79,27 @@ Installing Red
                for the PATH changes to take effect.
 
 1. Open a command prompt (open Start, search for "command prompt", then click it)
-2. Create and activate a virtual environment (strongly recommended), see the section `using-venv`
-3. Run **one** of the following commands, depending on what extras you want installed
-
-  .. note::
-
-      If you're not inside an activated virtual environment, use ``py -3.8`` in place of
-      ``python``, and include the ``--user`` flag with all ``pip install`` commands, like this:
-
-      .. code-block:: none
-
-          py -3.8 -m pip install --user -U setuptools wheel
-          py -3.8 -m pip install --user -U Red-DiscordBot
+2. Run **one** of the following set of commands, depending on what extras you want installed
 
   * Normal installation:
 
     .. code-block:: none
 
-        python -m pip install -U setuptools wheel
+        python -m pip install -U pip setuptools wheel
         python -m pip install -U Red-DiscordBot
 
   * With PostgreSQL support:
 
     .. code-block:: none
 
-        python -m pip install -U setuptools wheel
+        python -m pip install -U pip setuptools wheel
         python -m pip install -U Red-DiscordBot[postgres]
 
 
+.. note::
+
+    These commands are also used for updating Red
+
 --------------------------
 Setting Up and Running Red
 --------------------------

docs/venv_guide.rst

@@ -9,14 +9,9 @@ problems. Firstly, simply choose how you'd like to create your virtual environme
 * :ref:`using-venv` (quick and easy, involves two commands)
 * :ref:`using-pyenv-virtualenv` (recommended if you installed Python with pyenv)
 
-**Why Should I Use a Virtual Environment?**
-
-90% of the installation and setup issues raised in our support channels are resolved when the user
-creates a virtual environment.
-
 **What Are Virtual Environments For?**
 
-Virtual environments allow you to isolate red's library dependencies, cog dependencies and python
+Virtual environments allow you to isolate Red's library dependencies, cog dependencies and python
 binaries from the rest of your system. It also makes sure Red and its dependencies are installed to
 a predictable location. It makes uninstalling Red as simple as removing a single folder, without
 worrying about losing your data or other things on your system becoming broken.
@@ -31,18 +26,18 @@ python.
 
 First, choose a directory where you would like to create your virtual environment. It's a good idea
 to keep it in a location which is easy to type out the path to. From now, we'll call it
-``redenv``.
+``redenv`` and it will be located in your home directory.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~
 ``venv`` on Linux or Mac
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Create your virtual environment with the following command::
 
-    python3.8 -m venv redenv
+    python3.8 -m venv ~/redenv
 
 And activate it with the following command::
 
-    source redenv/bin/activate
+    source ~/redenv/bin/activate
 
 .. important::
 
@@ -56,11 +51,11 @@ Continue reading `below <after-activating-virtual-environment>`.
 ~~~~~~~~~~~~~~~~~~~
 Create your virtual environment with the following command::
 
-    py -3.8 -m venv redenv
+    py -3.8 -m venv %userprofile%\redenv
 
 And activate it with the following command::
 
-    redenv\Scripts\activate.bat
+    %userprofile%\redenv\Scripts\activate.bat
 
 .. important::