[Docs] Update linux install docs, redo venv docs (#2920)

* [Docs] Update linux install docs, redo venv docs

Some of our pre-req installation docs needed updating on Windows - this adds new sections for Fedora Linux and Debian/Raspbian Buster, and also removes some unnecessary pre-requirements from other distributions. These have all been tested on fresh VPSes, installing Red both in venvs and with --user, and they all seem to work.

Also, apparently the venv docs were too scary before. These changes try to make it clear that it's easier to use than users may think.

This also includes a little note to stop users from accidentally installing Python with pyenv after installing pre-requirements on Ubuntu.

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Add changelog entries

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Update officially supported platforms in README.md

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Combine sections and add openSUSE

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Include example of using `--user` flag

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Use `py -3.7` on Windows outside of venv

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Reorganise changelog entries

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

README.md

@@ -85,12 +85,7 @@ community of cog repositories.**
 
 - [Windows](https://red-discordbot.readthedocs.io/en/stable/install_windows.html)
 - [MacOS](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
-- [Ubuntu](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
-- [Debian Stretch](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
-- [CentOS 7](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
-- [Arch Linux](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
-- [Raspbian Stretch](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
-
+- [Most major linux distributions](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
 
 If after reading the guide you are still experiencing issues, feel free to join the
 [Official Discord Server](https://discord.gg/red) and ask in the **#support** channel for help.

changelog.d/2558.docs.rst

@@ -0,0 +1 @@
+Updated linux install docs, adding sections for Fedora Linux, Debian/Raspbian Buster, and openSUSE.

changelog.d/2920.docs.rst

@@ -0,0 +1 @@
+Reworded virtual environment guide to make it sound less scary.

docs/install_linux_mac.rst

@@ -7,7 +7,8 @@ Installing Red on Linux or Mac
 .. warning::
 
     For safety reasons, DO NOT install Red with a root user. If you are unsure how to create
-    a new user, see the man page for the ``useradd`` command.
+    a new user on Linux, see `this guide by DigitalOcean
+    <https://www.digitalocean.com/community/tutorials/how-to-create-a-sudo-user-on-ubuntu-quickstart>`_.
 
 -------------------------------
 Installing the pre-requirements
@@ -21,6 +22,9 @@ The pre-requirements are:
  - git
  - Java Runtime Environment 8 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.
+
 .. _install-arch:
 
 ~~~~~~~~~~
@@ -29,48 +33,71 @@ Arch Linux
 
 .. code-block:: none
 
-    sudo pacman -Syu python-pip git base-devel jre8-openjdk
+    sudo pacman -Syu python python-pip git jre-openjdk-headless base-devel
 
 .. _install-centos:
-.. _install-fedora:
 .. _install-rhel:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-CentOS 7, Fedora, and RHEL
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
+CentOS and RHEL 7
+~~~~~~~~~~~~~~~~~
 
 .. code-block:: none
 
     yum -y groupinstall development
     yum -y install https://centos7.iuscommunity.org/ius-release.rpm
     sudo yum install zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel \
-    openssl-devel xz xz-devel libffi-devel git2u java-1.8.0-openjdk
+      openssl-devel xz xz-devel libffi-devel findutils git2u java-1.8.0-openjdk
 
 Complete the rest of the installation by `installing Python 3.7 with pyenv <install-python-pyenv>`.
 
 .. _install-debian:
 .. _install-raspbian:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~
+Debian and Raspbian
+~~~~~~~~~~~~~~~~~~~
+
+Debian and Raspbian Buster
+**************************
+
+Debian and Raspbian Buster have all required packages available in official repositories. Install
+them with apt:
+
+.. code-block:: none
+
+    sudo apt update
+    sudo apt install python3 python3-dev python3-venv python3-pip git default-jre-headless \
+      build-essential
+
 Debian and Raspbian Stretch
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. warning::
-
-    Audio will not work on Raspberry Pi's **below** 2B. This is a CPU problem and
-    *cannot* be fixed.
+***************************
 
 We recommend installing pyenv as a method of installing non-native versions of python on
 Debian/Raspbian Stretch. This guide will tell you how. First, run the following commands:
 
 .. code-block:: none
 
-    sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev \
-    libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
-    xz-utils tk-dev libffi-dev liblzma-dev python3-openssl git unzip default-jre
+    sudo apt update
+    sudo apt install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
+      libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev \
+      liblzma-dev python3-openssl git default-jre-headless
 
 Complete the rest of the installation by `installing Python 3.7 with pyenv <install-python-pyenv>`.
 
+.. _install-fedora:
+
+~~~~~~~~~~~~
+Fedora Linux
+~~~~~~~~~~~~
+
+Fedora Linux 29 and above has all required packages available in official repositories. Install
+them with dnf:
+
+.. code-block:: none
+
+    sudo dnf install python3 python3-devel git java-latest-openjdk-headless @development-tools
+
 .. _install-mac:
 
 ~~~
@@ -94,42 +121,83 @@ one-by-one:
     brew tap caskroom/versions
     brew cask install homebrew/cask-versions/adoptopenjdk8
 
-It's possible you will have network issues. If so, go in your Applications folder, inside it, go in the Python 3.7 folder then double click ``Install certificates.command``
+It's possible you will have network issues. If so, go in your Applications folder, inside it, go in
+the Python 3.7 folder then double click ``Install certificates.command``.
+
+.. _install-opensuse:
+
+~~~~~~~~
+openSUSE
+~~~~~~~~
+
+openSUSE Leap
+*************
+
+We recommend installing a community package to get Python 3.7 on openSUSE Leap. This package will
+be installed to the ``/opt`` directory.
+
+First, add the Opt-Python community repository:
+
+.. code-block:: none
+
+    source /etc/os-release
+    sudo zypper ar -f https://download.opensuse.org/repositories/home:/Rotkraut:/Opt-Python/openSUSE_Leap_${VERSION_ID}/ Opt-Python
+
+Now install the pre-requirements with zypper:
+
+.. code-block:: none
+
+    sudo zypper install opt-python37 opt-python37-setuptools git-core java-11-openjdk-headless
+    sudo zypper install -t pattern devel_basis
+
+Since Python is now installed to ``/opt/python``, we should add it to PATH. You can add a file in
+``/etc/profile.d/`` to do this:
+
+.. code-block:: none
+
+    echo 'export PATH="/opt/python/bin:$PATH"' | sudo tee /etc/profile.d/opt-python.sh
+    source /etc/profile.d/opt-python.sh
+
+Now, install pip with easy_install:
+
+.. code-block:: none
+
+    sudo /opt/python/bin/easy_install-3.7 pip
+
+openSUSE Tumbleweed
+*******************
+
+openSUSE Tumbleweed has all required dependencies available in official repositories. Install them
+with zypper:
+
+.. code-block:: none
+
+    sudo zypper install python3-base python3-pip git-core java-12-openjdk-headless
+    sudo zypper install -t pattern devel_basis
 
 .. _install-ubuntu:
-.. _install-ubuntu-bionic:
-.. _install-ubuntu-cosmic:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Ubuntu 18.04 Bionic Beaver and 18.10 Cosmic Cuttlefish
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~
+Ubuntu
+~~~~~~
+
+.. note:: **Ubuntu 16.04 Users**
+
+    You must add a 3rd-party repository to install Python 3.7 on Ubuntu 16.04 with apt. We
+    recommend the ``deadsnakes`` repository:
+
+    .. code-block:: none
+
+        sudo apt install software-properties-common
+        sudo add-apt-repository ppa:deadsnakes/ppa
+
+Install the pre-requirements with apt:
 
 .. code-block:: none
 
-    sudo apt install python3.7 python3.7-dev python3.7-venv python3-pip build-essential \
-    libssl-dev libffi-dev git unzip default-jre -y
-
-.. _install-ubuntu-xenial:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Ubuntu 16.04 Xenial Xerus
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We recommend adding the ``deadsnakes`` apt repository to install Python 3.7 or greater:
-
-.. code-block:: none
-
-    sudo apt install software-properties-common
-    sudo add-apt-repository ppa:deadsnakes/ppa
     sudo apt update
-
-Now, install python, pip, git and java with the following commands:
-
-.. code-block:: none
-
-    sudo apt install python3.7 python3.7-dev build-essential libssl-dev libffi-dev git \
-    unzip default-jre curl -y
-    curl https://bootstrap.pypa.io/get-pip.py | sudo python3.7
+    sudo apt install python3.7 python3.7-dev python3.7-venv python3-pip git default-jre-headless \
+      build-essential
 
 .. _install-python-pyenv:
 
@@ -137,6 +205,11 @@ Now, install python, pip, git and java with the following commands:
 Installing Python with pyenv
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. note::
+
+    If you followed one of the sections above, and weren't linked here afterwards, you should skip
+    this section.
+
 On distributions where Python 3.7 needs to be compiled from source, we recommend the use of pyenv.
 This simplifies the compilation process and has the added bonus of simplifying setting up Red in a
 virtual environment.
@@ -152,7 +225,7 @@ Then run the following command:
 
 .. code-block:: none
 
-    CONFIGURE_OPTS=--enable-optimizations pyenv install 3.7.2 -v
+    CONFIGURE_OPTS=--enable-optimizations pyenv install 3.7.4 -v
 
 This may take a long time to complete, depending on your hardware. For some machines (such as
 Raspberry Pis and micro-tier VPSes), it may take over an hour; in this case, you may wish to remove
@@ -164,7 +237,7 @@ After that is finished, run:
 
 .. code-block:: none
 
-    pyenv global 3.7.2
+    pyenv global 3.7.4
 
 Pyenv is now installed and your system should be configured to run Python 3.7.
 
@@ -172,8 +245,8 @@ Pyenv is now installed and your system should be configured to run Python 3.7.
 Creating a Virtual Environment
 ------------------------------
 
-We **strongly** recommend installing Red into a virtual environment. See the section
-`installing-in-virtual-environment`.
+We **strongly** recommend 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:
 
@@ -186,7 +259,11 @@ 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.7 -m pip`` commands.
+    ``python3.7 -m pip install`` commands, like this:
+
+    .. code-block:: none
+
+        python3.7 -m pip install --user -U Red-DiscordBot
 
 To install without MongoDB support:
 

docs/install_windows.rst

@@ -36,8 +36,8 @@ Manually installing dependencies
 
 * `Python <https://www.python.org/downloads/>`_ - Red needs Python 3.7.0 or greater
 
-.. note:: Please make sure that the box to add Python to PATH is CHECKED, otherwise
-          you may run into issues when trying to run Red.
+.. attention:: Please make sure that the box to add Python to PATH is CHECKED, otherwise
+               you may run into issues when trying to run Red.
 
 * `Git <https://git-scm.com/download/win>`_
 
@@ -62,8 +62,12 @@ Installing Red
 
   .. note::
 
-      If you're not inside an activated virtual environment, include the ``--user`` flag with all
-      ``pip`` commands.
+      If you're not inside an activated virtual environment, use ``py -3.7`` in place of
+      ``python``, and include the ``--user`` flag with all ``pip install`` commands, like this:
+
+      .. code-block:: none
+
+          py -3.7 -m pip install --user -U Red-DiscordBot
 
   * Normal installation:
 

docs/venv_guide.rst

@@ -3,9 +3,23 @@
 =======================================
 Installing Red in a Virtual Environment
 =======================================
+Creating a virtual environment is really easy and usually prevents many common installation
+problems. Firstly, simply choose how you'd like to create your virtual environment:
+
+* :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
-binaries from the rest of your system. It is strongly recommended you use this if you use python
-for more than just Red.
+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.
 
 .. _using-venv:
 
@@ -17,18 +31,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
-``path/to/venv/`` (or ``path\to\venv\`` on Windows).
+``redenv``.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~
 ``venv`` on Linux or Mac
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Create your virtual environment with the following command::
 
-    python3.7 -m venv path/to/venv/
+    python3.7 -m venv redenv
 
 And activate it with the following command::
 
-    source path/to/venv/bin/activate
+    source redenv/bin/activate
 
 .. important::
 
@@ -42,11 +56,11 @@ Continue reading `below <after-activating-virtual-environment>`.
 ~~~~~~~~~~~~~~~~~~~
 Create your virtual environment with the following command::
 
-    python -m venv path\to\venv\
+    py -3.7 -m venv redenv
 
 And activate it with the following command::
 
-    path\to\venv\Scripts\activate.bat
+    redenv\Scripts\activate.bat
 
 .. important::
 
@@ -86,7 +100,8 @@ Now activate your virtualenv with the following command::
 .. important::
 
     You must activate the virtual environment with the above command every time you open a new
-    shell to run, install or update Red.
+    shell to run, install or update Red. You can check out other commands like ``pyenv local`` and
+    ``pyenv global`` if you wish to keep the virtualenv activated all the time.
 
 Continue reading `below <after-activating-virtual-environment>`.