Split documents per OS, fix few things, drop and add few OSes (#5328)

* Exclude include files from being built

* Split install guides into multiple documents (one per OS/version combo)

* Update references

* Unify anchor names

* Update pyenv requirements in CentOS 7 guide

* Update install guides for RHEL derivatives to not use pyenv

* Add guide for Rocky Linux 8

* 8.4+ -> 8.4-8.x

* Add 'the'

docs/changelog_3_3_0.rst

@@ -650,7 +650,7 @@ Dev Cog
 Documentation changes
 ---------------------
 
-- Fixed install instructions for Mac in `install_linux_mac` (:issue:`3675`, :issue:`3436`)
+- Fixed install instructions for Mac (:issue:`3675`, :issue:`3436`)
 - Windows install instructions now use ``choco upgrade`` commands instead of ``choco install`` to ensure up-to-date packages (:issue:`3684`)
 
 

docs/changelog_3_4_0.rst

@@ -653,7 +653,7 @@ Documentation changes
 - Added information about the Red Index to `guide_publish_cogs` (:issue:`4778`)
 - Restructured the host list (:issue:`4710`)
 - Clarified how to use pm2 with ``pyenv virtualenv`` (:issue:`4709`)
-- Updated the pip command for Red with the postgres extra in `install_linux_mac` document to work on zsh shell (:issue:`4697`)
+- Updated the pip command for Red with the postgres extra in Linux/macOS install guide to work on zsh shell (:issue:`4697`)
 - Updated Python version in ``pyenv`` and Windows instructions (:issue:`4770`)
 
 
@@ -873,7 +873,7 @@ Documentation changes
 ---------------------
 
 - Added `cog guide for Cleanup cog <cleanup>` (:issue:`4488`)
-- Removed multi-line commands from `install_linux_mac` to avoid confusing readers (:issue:`4550`)
+- Removed multi-line commands from Linux install guides to avoid confusing readers (:issue:`4550`)
 
 
 Redbot 3.4.1 (2020-10-27)

docs/conf.py

@@ -86,7 +86,13 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    # to ensure that include files (partial pages) aren't built, exclude them
+    "**/_includes/**",
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"

docs/index.rst

@@ -12,8 +12,7 @@ Welcome to Red - Discord Bot's documentation!
     :maxdepth: 1
     :caption: Installation Guides:
 
-    install_windows
-    install_linux_mac
+    install_guides/index
     bot_application_guide
     update_red
     about_venv

docs/install_guides/_includes/create-env-with-pyenv-virtualenv.rst

@@ -0,0 +1,44 @@
+------------------------------
+Creating a Virtual Environment
+------------------------------
+
+.. tip::
+
+    If you want to learn more about virtual environments, see page: `about-venvs`
+
+We require installing Red into a virtual environment. Don't be scared, it's very
+straightforward.
+
+**************************
+Using ``pyenv virtualenv``
+**************************
+
+Using ``pyenv virtualenv`` saves you the headache of remembering where you installed your virtual
+environments. This option is only available if you installed Python with pyenv.
+
+First, ensure your pyenv interpreter is set to python 3.8.1 or greater with the following command:
+
+.. prompt:: bash
+
+    pyenv version
+
+Now, create a virtual environment with the following command:
+
+.. prompt:: bash
+
+    pyenv virtualenv <name>
+
+Replace ``<name>`` with whatever you like. If you ever forget what you named it,
+you can always use the command ``pyenv versions`` to list all virtual environments.
+
+Now activate your virtualenv with the following command:
+
+.. prompt:: bash
+
+    pyenv shell <name>
+
+.. important::
+
+    You must activate the virtual environment with the above command every time you open a new
+    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.

docs/install_guides/_includes/create-env-with-venv.rst

@@ -0,0 +1,38 @@
+------------------------------
+Creating a Virtual Environment
+------------------------------
+
+.. tip::
+
+    If you want to learn more about virtual environments, see page: `about-venvs`
+
+We require installing Red into a virtual environment. Don't be scared, it's very
+straightforward.
+
+**************
+Using ``venv``
+**************
+
+This is the quickest way to get your virtual environment up and running, as `venv` is shipped with
+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`` and it will be located in your home directory.
+
+Create your virtual environment with the following command:
+
+.. prompt:: bash
+
+    python3.9 -m venv ~/redenv
+
+And activate it with the following command:
+
+.. prompt:: bash
+
+    source ~/redenv/bin/activate
+
+.. important::
+
+    You must activate the virtual environment with the above command every time you open a new
+    shell to run, install or update Red.

docs/install_guides/_includes/install-and-setup-red-unix.rst

@@ -0,0 +1,56 @@
+--------------
+Installing Red
+--------------
+
+Choose one of the following commands to install Red.
+
+To install without additional config backend support:
+
+.. prompt:: bash
+    :prompts: (redenv) $
+
+    python -m pip install -U pip setuptools wheel
+    python -m pip install -U Red-DiscordBot
+
+Or, to install with PostgreSQL support:
+
+.. prompt:: bash
+    :prompts: (redenv) $
+
+    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
+--------------------------
+
+After installation, set up your instance with the following command:
+
+.. prompt:: bash
+    :prompts: (redenv) $
+
+    redbot-setup
+
+This will set the location where data will be stored, as well as your
+storage backend and the name of the instance (which will be used for
+running the bot).
+
+Once done setting up the instance, run the following command to run Red:
+
+.. prompt:: bash
+    :prompts: (redenv) $
+
+    redbot <your instance name>
+
+It will walk through the initial setup, asking for your token and a prefix.
+You can find out how to obtain a token with
+`this guide <../bot_application_guide>`.
+
+.. tip::
+   If it's the first time you're using Red, you should check our `getting-started` guide
+   that will walk you through all essential information on how to interact with Red.

docs/install_guides/_includes/install-guide-rhel-derivatives.rst

@@ -0,0 +1,26 @@
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+Red Hat Enterprise Linux (RHEL) 8.4-8.x and its derivatives have all required packages available in official repositories.
+Install them with dnf:
+
+.. prompt:: bash
+
+    sudo dnf -y update
+    sudo dnf -y group install development
+    sudo dnf -y install python39 python39-pip python39-devel java-11-openjdk-headless nano git
+
+Set ``java`` executable to point to Java 11:
+
+.. prompt:: bash
+
+    sudo alternatives --set java "java-11-openjdk.$(uname -i)"
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/_includes/install-python-pyenv.rst

@@ -0,0 +1,34 @@
+----------------------------
+Installing Python with pyenv
+----------------------------
+
+On distributions where Python 3.9 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.
+
+.. prompt:: bash
+
+    command -v pyenv && pyenv update || curl https://pyenv.run | bash
+
+**After this command, you may see a warning about 'pyenv' not being in the load path. Follow the
+instructions given to fix that, then close and reopen your shell.**
+
+Then run the following command:
+
+.. prompt:: bash
+
+    CONFIGURE_OPTS=--enable-optimizations pyenv install 3.9.7 -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
+the ``CONFIGURE_OPTS=--enable-optimizations`` part from the front of the command, which will
+drastically reduce the install time. However, be aware that this will make Python run about 10%
+slower.
+
+After that is finished, run:
+
+.. prompt:: bash
+
+    pyenv global 3.9.7
+
+Pyenv is now installed and your system should be configured to run Python 3.9.

docs/install_guides/_includes/install-python38-pyenv.rst

@@ -0,0 +1,34 @@
+----------------------------
+Installing Python with pyenv
+----------------------------
+
+On distributions where Python 3.8 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.
+
+.. prompt:: bash
+
+    command -v pyenv && pyenv update || curl https://pyenv.run | bash
+
+**After this command, you may see a warning about 'pyenv' not being in the load path. Follow the
+instructions given to fix that, then close and reopen your shell.**
+
+Then run the following command:
+
+.. prompt:: bash
+
+    CONFIGURE_OPTS=--enable-optimizations pyenv install 3.8.12 -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
+the ``CONFIGURE_OPTS=--enable-optimizations`` part from the front of the command, which will
+drastically reduce the install time. However, be aware that this will make Python run about 10%
+slower.
+
+After that is finished, run:
+
+.. prompt:: bash
+
+    pyenv global 3.8.12
+
+Pyenv is now installed and your system should be configured to run Python 3.8.

docs/install_guides/_includes/linux-preamble.rst

@@ -0,0 +1,5 @@
+.. warning::
+
+    For safety reasons, DO NOT install Red with a root user. If you are unsure how to create
+    a new user on Linux, see `this guide by DigitalOcean
+    <https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart>`_.

docs/install_guides/arch.rst

@@ -0,0 +1,23 @@
+.. _install-arch:
+
+============================
+Installing Red on Arch Linux
+============================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+Install the pre-requirements with pacman:
+
+.. prompt:: bash
+
+    sudo pacman -Syu python python-pip git jre11-openjdk-headless base-devel nano
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/centos-7.rst

@@ -0,0 +1,42 @@
+.. _install-centos-7:
+
+==========================
+Installing Red on CentOS 7
+==========================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+Install the pre-requirements with yum:
+
+.. prompt:: bash
+
+    sudo yum -y groupinstall development
+    sudo yum -y install gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel java-11-openjdk-headless nano git
+
+In order to install gcc 8, we'll use SCL repository:
+
+.. prompt:: bash
+
+    sudo yum -y install centos-release-scl
+    sudo yum -y install devtoolset-8-gcc devtoolset-8-gcc-c++
+    echo "source scl_source enable devtoolset-8" >> ~/.bashrc
+    source ~/.bashrc
+
+In order to install Git 2.11 or greater, we recommend adding the IUS repository:
+
+.. prompt:: bash
+
+    sudo yum -y install https://repo.ius.io/ius-release-el7.rpm
+    sudo yum -y swap git git224
+
+.. Include common instructions:
+
+.. include:: _includes/install-python-pyenv.rst
+
+.. include:: _includes/create-env-with-pyenv-virtualenv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/centos-8.rst

@@ -0,0 +1,7 @@
+.. _install-centos-8:
+
+=============================
+Installing Red on CentOS 8.4+
+=============================
+
+.. include:: _includes/install-guide-rhel-derivatives.rst

docs/install_guides/centos-stream-8.rst

@@ -0,0 +1,7 @@
+.. _install-centos-stream-8:
+
+=================================
+Installing Red on CentOS Stream 8
+=================================
+
+.. include:: _includes/install-guide-rhel-derivatives.rst

docs/install_guides/debian-10.rst

@@ -0,0 +1,28 @@
+.. _install-debian-10:
+
+==================================
+Installing Red on Debian 10 Buster
+==================================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+We recommend installing pyenv as a method of installing non-native versions of Python on
+Debian Buster. This guide will tell you how. First, run the following commands:
+
+.. prompt:: bash
+
+    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-headless nano
+    CXX=/usr/bin/g++
+
+.. Include common instructions:
+
+.. include:: _includes/install-python-pyenv.rst
+
+.. include:: _includes/create-env-with-pyenv-virtualenv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/debian-11.rst

@@ -0,0 +1,25 @@
+.. _install-debian-11:
+
+====================================
+Installing Red on Debian 11 Bullseye
+====================================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+Debian 11 "Bullseye" has all required packages available in official repositories. Install them
+with apt:
+
+.. prompt:: bash
+
+    sudo apt update
+    sudo apt -y install python3 python3-dev python3-venv python3-pip git openjdk-11-jre-headless build-essential nano
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/fedora.rst

@@ -0,0 +1,24 @@
+.. _install-fedora:
+
+==============================
+Installing Red on Fedora Linux
+==============================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+Fedora Linux 33 and above has all required packages available in official repositories. Install
+them with dnf:
+
+.. prompt:: bash
+
+    sudo dnf -y install python39 git java-11-openjdk-headless @development-tools nano
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/index.rst

@@ -0,0 +1,31 @@
+.. _install-guides:
+
+Installing Red
+==============
+
+The list below shows the installation guides available based on the operating system being used.
+
+If you want to host Red on a VPS and are unsure what operating system you should choose,
+we recommend **Ubuntu 20.04 LTS**.
+
+.. toctree::
+   :maxdepth: 1
+
+   windows
+   mac
+   arch
+   centos-7
+   centos-8
+   centos-stream-8
+   debian-10
+   debian-11
+   fedora
+   opensuse-leap-15
+   opensuse-tumbleweed
+   oracle-linux-8
+   raspberry-pi-os-10
+   rhel-8
+   rocky-linux-8
+   ubuntu-1804
+   ubuntu-2004
+   ubuntu-non-lts

docs/install_guides/mac.rst

@@ -0,0 +1,34 @@
+.. _install-mac:
+
+=======================
+Installing Red on macOS
+=======================
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+To install pre-requirements, we first have to install Brew.
+In Finder or Spotlight, search for and open *Terminal*. In the terminal, paste the
+following, then press Enter:
+
+.. prompt:: bash
+
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+
+After the installation, install the required packages by pasting the commands and pressing enter,
+one-by-one:
+
+.. prompt:: bash
+
+    brew install python@3.9
+    echo 'export PATH="$(brew --prefix)/opt/python@3.9/bin:$PATH"' >> ~/.profile
+    source ~/.profile
+    brew install git
+    brew install --cask adoptopenjdk/openjdk/adoptopenjdk11
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/opensuse-leap-15.rst

@@ -0,0 +1,54 @@
+.. _install-opensuse-leap-15:
+
+=====================================
+Installing Red on openSUSE Leap 15.2+
+=====================================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+We recommend installing a community package to get Python 3.9 on openSUSE Leap 15.2+. This package will
+be installed to the ``/opt`` directory.
+
+First, add the Opt-Python community repository:
+
+.. prompt:: bash
+
+    source /etc/os-release
+    sudo zypper -n ar -f https://download.opensuse.org/repositories/home:/Rotkraut:/Opt-Python/openSUSE_Leap_${VERSION_ID}/ Opt-Python
+    sudo zypper -n --gpg-auto-import-keys ref
+
+Now install the pre-requirements with zypper:
+
+.. prompt:: bash
+
+    sudo zypper -n install opt-python39 opt-python39-setuptools git-core java-11-openjdk-headless nano
+    sudo zypper -n 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:
+
+.. prompt:: bash
+
+    echo 'export PATH="/opt/python/bin:$PATH"' | sudo tee /etc/profile.d/opt-python.sh
+    source /etc/profile.d/opt-python.sh
+
+Now, bootstrap pip with ensurepip:
+
+.. prompt:: bash
+
+    sudo /opt/python/bin/python3.9 -m ensurepip --altinstall
+
+.. note::
+
+    After this command, a warning about running pip as root might be printed.
+    For this specific command, this warning can be safely ignored.
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/opensuse-tumbleweed.rst

@@ -0,0 +1,25 @@
+.. _install-opensuse-tumbleweed:
+
+=====================================
+Installing Red on openSUSE Tumbleweed
+=====================================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+openSUSE Tumbleweed has all required dependencies available in official repositories. Install them
+with zypper:
+
+.. prompt:: bash
+
+    sudo zypper -n install python39-base python39-pip git-core java-11-openjdk-headless nano
+    sudo zypper -n install -t pattern devel_basis
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/oracle-linux-8.rst

@@ -0,0 +1,7 @@
+.. _install-oracle-linux-8:
+
+======================================
+Installing Red on Oracle Linux 8.4-8.x
+======================================
+
+.. include:: _includes/install-guide-rhel-derivatives.rst

docs/install_guides/raspberry-pi-os-10.rst

@@ -0,0 +1,28 @@
+.. _install-raspberry-pi-os-10:
+
+=================================
+Installing Red on Raspberry Pi OS
+=================================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+We recommend installing pyenv as a method of installing non-native versions of Python on
+Raspberry Pi OS. This guide will tell you how. First, run the following commands:
+
+.. prompt:: bash
+
+    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-headless nano
+    CXX=/usr/bin/g++
+
+.. Include common instructions:
+
+.. include:: _includes/install-python38-pyenv.rst
+
+.. include:: _includes/create-env-with-pyenv-virtualenv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/rhel-8.rst

@@ -0,0 +1,7 @@
+.. _install-rhel-8:
+
+=========================================================
+Installing Red on Red Hat Enterprise Linux (RHEL) 8.4-8.x
+=========================================================
+
+.. include:: _includes/install-guide-rhel-derivatives.rst

docs/install_guides/rocky-linux-8.rst

@@ -0,0 +1,7 @@
+.. _install-rocky-linux-8:
+
+===============================
+Installing Red on Rocky Linux 8
+===============================
+
+.. include:: _includes/install-guide-rhel-derivatives.rst

docs/install_guides/ubuntu-1804.rst

@@ -0,0 +1,37 @@
+.. _install-ubuntu-1804:
+
+==================================
+Installing Red on Ubuntu 18.04 LTS
+==================================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
+
+.. prompt:: bash
+
+    sudo apt update
+    sudo apt -y install software-properties-common
+    sudo add-apt-repository -y ppa:git-core/ppa
+
+We recommend adding the ``deadsnakes`` ppa to install Python 3.9:
+
+.. prompt:: bash
+
+    sudo add-apt-repository -y ppa:deadsnakes/ppa
+
+Now install the pre-requirements with apt:
+
+.. prompt:: bash
+
+    sudo apt -y install python3.9 python3.9-dev python3.9-venv python3-pip git openjdk-11-jre-headless build-essential nano
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/ubuntu-2004.rst

@@ -0,0 +1,31 @@
+.. _install-ubuntu-2004:
+
+==================================
+Installing Red on Ubuntu 20.04 LTS
+==================================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
+
+.. prompt:: bash
+
+    sudo apt update
+    sudo apt -y install software-properties-common
+    sudo add-apt-repository -y ppa:git-core/ppa
+
+Now install the pre-requirements with apt:
+
+.. prompt:: bash
+
+    sudo apt -y install python3.9 python3.9-dev python3.9-venv python3-pip git openjdk-11-jre-headless build-essential nano
+
+.. Include common instructions:
+
+.. include:: _includes/create-env-with-venv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/ubuntu-non-lts.rst

@@ -0,0 +1,35 @@
+.. _install-ubuntu-non-lts:
+
+=========================================
+Installing Red on Ubuntu non-LTS versions
+=========================================
+
+.. include:: _includes/linux-preamble.rst
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
+
+.. prompt:: bash
+
+    sudo apt update
+    sudo apt -y install software-properties-common
+    sudo add-apt-repository -yu 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:
+
+.. prompt:: bash
+
+    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-headless nano
+    CXX=/usr/bin/g++
+
+.. Include common instructions:
+
+.. include:: _includes/install-python-pyenv.rst
+
+.. include:: _includes/create-env-with-pyenv-virtualenv.rst
+
+.. include:: _includes/install-and-setup-red-unix.rst

docs/install_guides/windows.rst

@@ -10,15 +10,6 @@ Installing the pre-requirements
 
 Please install the pre-requirements by following instructions from one of the following subsections.
 
-The pre-requirements are:
- - Python 3.8.1 or greater
- - Pip 18.1 or greater
- - Git 2.11+
- - Java Runtime Environment 11 (for audio support)
-
-We also recommend installing some basic compiler tools, in case our dependencies don't provide
-pre-built "wheels" for your architecture.
-
 .. contents:: Choose a method of installing pre-requirements:
     :local:
 
@@ -176,7 +167,7 @@ Once done setting up the instance, run the following command to run Red:
 
 It will walk through the initial setup, asking for your token and a prefix.
 You can find out how to obtain a token with
-`this guide <bot_application_guide>`.
+`this guide <../bot_application_guide>`.
 
 .. tip::
    If it's the first time you're using Red, you should check our `getting-started` guide

docs/install_linux_mac.rst

@@ -1,516 +0,0 @@
-.. _linux-mac-install-guide:
-
-==============================
-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 on Linux, see `this guide by DigitalOcean
-    <https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart>`_.
-
--------------------------------
-Installing the pre-requirements
--------------------------------
-
-Please install the pre-requirements using the commands listed for your operating system.
-
-The pre-requirements are:
- - Python 3.8.1 or greater
- - Pip 18.1 or greater
- - Git 2.11+
- - Java Runtime Environment 11 (for audio support)
-
-We recommend installing the nano text editor as our guides may instruct you to create or edit some files. 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:
-
-~~~~~~~~~~
-Arch Linux
-~~~~~~~~~~
-
-.. prompt:: bash
-
-    sudo pacman -Syu python python-pip git jre11-openjdk-headless base-devel nano
-
-Continue by `creating-venv-linux`.
-
-----
-
-.. _install-centos7:
-.. _install-rhel7:
-
-~~~~~~~~~~~~~~~~~
-CentOS and RHEL 7
-~~~~~~~~~~~~~~~~~
-
-.. prompt:: bash
-
-    sudo yum -y groupinstall development
-    sudo yum -y install zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel xz xz-devel tk-devel libffi-devel findutils java-11-openjdk-headless nano
-    sudo yum -y install centos-release-scl
-    sudo yum -y install devtoolset-8-gcc devtoolset-8-gcc-c++
-    echo "source scl_source enable devtoolset-8" >> ~/.bashrc
-    source ~/.bashrc
-
-In order to install Git 2.11 or greater, we recommend adding the IUS repository:
-
-.. prompt:: bash
-
-    sudo yum -y install https://repo.ius.io/ius-release-el7.rpm
-    sudo yum -y swap git git224
-
-Complete the rest of the installation by `installing Python 3.9 with pyenv <install-python-pyenv>`.
-
-----
-
-.. _install-centos:
-.. _install-rhel:
-
-~~~~~~~~~~~~~~~~~
-CentOS and RHEL 8
-~~~~~~~~~~~~~~~~~
-
-.. prompt:: bash
-
-    sudo yum -y install epel-release
-    sudo yum -y update
-    sudo yum -y groupinstall development
-    sudo yum -y install git zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel xz xz-devel tk-devel libffi-devel findutils java-11-openjdk-headless nano
-
-Complete the rest of the installation by `installing Python 3.9 with pyenv <install-python-pyenv>`.
-
-----
-
-.. _install-debian:
-.. _install-raspbian:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Debian 10 Buster and Raspberry Pi OS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We recommend installing pyenv as a method of installing non-native versions of python on
-Debian/Raspbian Buster. This guide will tell you how. First, run the following commands:
-
-.. prompt:: bash
-
-    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-headless nano
-    CXX=/usr/bin/g++
-
-Complete the rest of the installation by `installing Python 3.9 with pyenv <install-python-pyenv>`.
-
----
-
-.. _install-debian11:
-
-~~~~~~~~~~~~~~~~~~~~
-Debian 11 Bullseye
-~~~~~~~~~~~~~~~~~~~~
-
-Debian 11 "Bullseye" has all required packages available in official repositories. Install them
-with apt:
-
-.. prompt:: bash
-
-    sudo apt update
-    sudo apt -y install python3 python3-dev python3-venv python3-pip git openjdk-11-jre-headless build-essential nano
-
-Continue by `creating-venv-linux`.
-
-----
-
-.. _install-fedora:
-
-~~~~~~~~~~~~
-Fedora Linux
-~~~~~~~~~~~~
-
-Fedora Linux 33 and above has all required packages available in official repositories. Install
-them with dnf:
-
-.. prompt:: bash
-
-    sudo dnf -y install python39 git java-11-openjdk-headless @development-tools nano
-
-Continue by `creating-venv-linux`.
-
-----
-
-.. _install-mac:
-
-~~~
-Mac
-~~~
-
-Install Brew: in Finder or Spotlight, search for and open *Terminal*. In the terminal, paste the
-following, then press Enter:
-
-.. prompt:: bash
-
-    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
-
-After the installation, install the required packages by pasting the commands and pressing enter,
-one-by-one:
-
-.. prompt:: bash
-
-    brew install python@3.9
-    echo 'export PATH="$(brew --prefix)/opt/python@3.9/bin:$PATH"' >> ~/.profile
-    source ~/.profile
-    brew install git
-    brew install --cask adoptopenjdk/openjdk/adoptopenjdk11
-
-Continue by `creating-venv-linux`.
-
-----
-
-.. _install-opensuse:
-
-~~~~~~~~
-openSUSE
-~~~~~~~~
-
-openSUSE Leap 15.2+
-*******************
-
-We recommend installing a community package to get Python 3.9 on openSUSE Leap 15.2+. This package will
-be installed to the ``/opt`` directory.
-
-First, add the Opt-Python community repository:
-
-.. prompt:: bash
-
-    source /etc/os-release
-    sudo zypper -n ar -f https://download.opensuse.org/repositories/home:/Rotkraut:/Opt-Python/openSUSE_Leap_${VERSION_ID}/ Opt-Python
-    sudo zypper -n --gpg-auto-import-keys ref
-
-Now install the pre-requirements with zypper:
-
-.. prompt:: bash
-
-    sudo zypper -n install opt-python39 opt-python39-setuptools git-core java-11-openjdk-headless nano
-    sudo zypper -n 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:
-
-.. prompt:: bash
-
-    echo 'export PATH="/opt/python/bin:$PATH"' | sudo tee /etc/profile.d/opt-python.sh
-    source /etc/profile.d/opt-python.sh
-
-Now, bootstrap pip with ensurepip:
-
-.. prompt:: bash
-
-    sudo /opt/python/bin/python3.9 -m ensurepip --altinstall
-
-.. note::
-
-    After this command, a warning about running pip as root might be printed.
-    For this specific command, this warning can be safely ignored.
-
-Continue by `creating-venv-linux`.
-
-openSUSE Tumbleweed
-*******************
-
-openSUSE Tumbleweed has all required dependencies available in official repositories. Install them
-with zypper:
-
-.. prompt:: bash
-
-    sudo zypper -n install python39-base python39-pip git-core java-11-openjdk-headless nano
-    sudo zypper -n install -t pattern devel_basis
-
-Continue by `creating-venv-linux`.
-
-----
-
-.. _install-ubuntu-1804:
-
-~~~~~~~~~~~~~~~~
-Ubuntu 18.04 LTS
-~~~~~~~~~~~~~~~~
-
-We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
-
-.. prompt:: bash
-
-    sudo apt update
-    sudo apt -y install software-properties-common
-    sudo add-apt-repository -y ppa:git-core/ppa
-
-We recommend adding the ``deadsnakes`` ppa to install Python 3.9:
-
-.. prompt:: bash
-
-    sudo add-apt-repository -y ppa:deadsnakes/ppa
-
-Now install the pre-requirements with apt:
-
-.. prompt:: bash
-
-    sudo apt -y install python3.9 python3.9-dev python3.9-venv python3-pip git openjdk-11-jre-headless build-essential nano
-
-Continue by `creating-venv-linux`.
-
-----
-
-.. _install-ubuntu:
-
-~~~~~~~~~~~~~~~~
-Ubuntu 20.04 LTS
-~~~~~~~~~~~~~~~~
-
-We recommend adding the ``git-core`` ppa to install Git 2.11 or greater:
-
-.. prompt:: bash
-
-    sudo apt update
-    sudo apt -y install software-properties-common
-    sudo add-apt-repository -y ppa:git-core/ppa
-
-Now install the pre-requirements with apt:
-
-.. prompt:: bash
-
-    sudo apt -y install python3.9 python3.9-dev python3.9-venv python3-pip git openjdk-11-jre-headless build-essential nano
-
-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:
-
-.. prompt:: bash
-
-    sudo apt update
-    sudo apt -y install software-properties-common
-    sudo add-apt-repository -yu 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:
-
-.. prompt:: bash
-
-    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-headless nano
-    CXX=/usr/bin/g++
-
-And then complete the rest of the installation by `installing Python 3.9 with pyenv <install-python-pyenv>`.
-
-----
-
-.. _install-python-pyenv:
-
-****************************
-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.9 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.
-
-.. prompt:: bash
-
-    command -v pyenv && pyenv update || curl https://pyenv.run | bash
-
-**After this command, you may see a warning about 'pyenv' not being in the load path. Follow the
-instructions given to fix that, then close and reopen your shell.**
-
-Then run the following command:
-
-.. prompt:: bash
-
-    CONFIGURE_OPTS=--enable-optimizations pyenv install 3.9.7 -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
-the ``CONFIGURE_OPTS=--enable-optimizations`` part from the front of the command, which will
-drastically reduce the install time. However, be aware that this will make Python run about 10%
-slower.
-
-After that is finished, run:
-
-.. prompt:: bash
-
-    pyenv global 3.9.7
-
-Pyenv is now installed and your system should be configured to run Python 3.9.
-
-Continue by `creating-venv-linux`.
-
-.. _creating-venv-linux:
-
-------------------------------
-Creating a Virtual Environment
-------------------------------
-
-.. tip::
-
-    If you want to learn more about virtual environments, see page: `about-venvs`
-
-We require installing Red into a virtual environment. Don't be scared, it's very
-straightforward.
-
-You have 2 options:
-
-* :ref:`using-venv` (quick and easy, involves just two commands)
-* :ref:`using-pyenv-virtualenv` (only available and recommended when you installed Python with pyenv)
-
-----
-
-.. _using-venv:
-
-**************
-Using ``venv``
-**************
-This is the quickest way to get your virtual environment up and running, as `venv` is shipped with
-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`` and it will be located in your home directory.
-
-Create your virtual environment with the following command:
-
-.. prompt:: bash
-
-    python3.9 -m venv ~/redenv
-
-And activate it with the following command:
-
-.. prompt:: bash
-
-    source ~/redenv/bin/activate
-
-.. important::
-
-    You must activate the virtual environment with the above command every time you open a new
-    shell to run, install or update Red.
-
-Continue by `installing-red-linux-mac`.
-
-----
-
-.. _using-pyenv-virtualenv:
-
-**************************
-Using ``pyenv virtualenv``
-**************************
-
-Using ``pyenv virtualenv`` saves you the headache of remembering where you installed your virtual
-environments. This option is only available if you installed Python with pyenv.
-
-First, ensure your pyenv interpreter is set to python 3.8.1 or greater with the following command:
-
-.. prompt:: bash
-
-    pyenv version
-
-Now, create a virtual environment with the following command:
-
-.. prompt:: bash
-
-    pyenv virtualenv <name>
-
-Replace ``<name>`` with whatever you like. If you ever forget what you named it,
-you can always use the command ``pyenv versions`` to list all virtual environments.
-
-Now activate your virtualenv with the following command:
-
-.. prompt:: bash
-
-    pyenv shell <name>
-
-.. important::
-
-    You must activate the virtual environment with the above command every time you open a new
-    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 by `installing-red-linux-mac`.
-
-.. _pyenv-installer: https://github.com/pyenv/pyenv-installer/blob/master/README.rst
-
-.. _installing-red-linux-mac:
-
---------------
-Installing Red
---------------
-
-Choose one of the following commands to install Red.
-
-To install without additional config backend support:
-
-.. prompt:: bash
-    :prompts: (redenv) $
-
-    python -m pip install -U pip setuptools wheel
-    python -m pip install -U Red-DiscordBot
-
-Or, to install with PostgreSQL support:
-
-.. prompt:: bash
-    :prompts: (redenv) $
-
-    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
---------------------------
-
-After installation, set up your instance with the following command:
-
-.. prompt:: bash
-    :prompts: (redenv) $
-
-    redbot-setup
-
-This will set the location where data will be stored, as well as your
-storage backend and the name of the instance (which will be used for
-running the bot).
-
-Once done setting up the instance, run the following command to run Red:
-
-.. prompt:: bash
-    :prompts: (redenv) $
-
-    redbot <your instance name>
-
-It will walk through the initial setup, asking for your token and a prefix.
-You can find out how to obtain a token with
-`this guide <bot_application_guide>`.
-
-.. tip::
-   If it's the first time you're using Red, you should check our `getting-started` guide
-   that will walk you through all essential information on how to interact with Red.

docs/update_red.rst

@@ -97,10 +97,7 @@ Red 3.1.X
 
 If you have Red 3.1.X, you will need to follow the install instructions for your operating system. Make sure that you turn your bot off first.
 
-- `Windows <install_windows>`
-- `Linux & Mac <install_linux_mac>`
-
-Follow every step to ensure you have all dependencies up-to-date and only skip ``redbot-setup`` step as you already have a bot instance.
+Go to the `install_guides/index` guide and follow every step to ensure you have all dependencies up-to-date and only skip the ``redbot-setup`` step as you already have a bot instance.
 
 **If you already have Red installed in a virtual environment, you will need to delete it before starting this process.**
 
@@ -139,9 +136,6 @@ Red 3.0.2 and older
 
 If you have Red 3.0.2 or older, you will need to follow the install instructions for your operating system. Make sure that you turn your bot off first.
 
-- `Windows <install_windows>`
-- `Linux & Mac <install_linux_mac>`
-
-Follow every step to ensure you have all dependencies up-to-date and only skip ``redbot-setup`` step as you already have a bot instance.
+Go to the `install_guides/index` guide and follow every step to ensure you have all dependencies up-to-date and only skip the ``redbot-setup`` step as you already have a bot instance.
 
 **If you already have Red installed in a virtual environment, you will need to delete it before starting this process.**