[Docs] Restructure venv instructions (put them in install guides) (#3495)

* docs: restructure venv instructions

* docs: add a warning about PowerShell usage

docs/about_venv.rst

@@ -0,0 +1,39 @@
+.. _about-venvs:
+
+==========================
+About Virtual Environments
+==========================
+Creating a virtual environment is really easy and usually prevents many common installation
+problems.
+
+**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. There is no performance overhead to using virtual environment
+and it saves you from a lot of troubles during setup. It also makes sure Red and its dependencies
+are installed to a predictable location which makes uninstalling Red as simple as removing a single folder,
+without worrying about losing your data or other things on your system becoming broken.
+
+
+--------------------------------------------
+Virtual Environments with Multiple Instances
+--------------------------------------------
+If you are running multiple instances of Red on the same machine, you have the option of either
+using the same virtual environment for all of them, or creating separate ones.
+
+.. note::
+
+    This only applies for multiple instances of V3. If you are running a V2 instance as well,
+    you **must** use separate virtual environments.
+
+The advantages of using a *single* virtual environment for all of your V3 instances are:
+
+- When updating Red, you will only need to update it once for all instances (however you will still need to restart all instances for the changes to take effect)
+- It will save space on your hard drive
+
+On the other hand, you may wish to update each of your instances individually.
+
+.. important::
+
+    Windows users with multiple instances should create *separate* virtual environments, as
+    updating multiple running instances at once is likely to cause errors.

docs/index.rst

@@ -14,7 +14,7 @@ Welcome to Red - Discord Bot's documentation!
 
     install_windows
     install_linux_mac
-    venv_guide
+    about_venv
     autostart_systemd
     autostart_pm2
 

docs/install_linux_mac.rst

@@ -348,8 +348,82 @@ Continue by `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. See the section `installing-in-virtual-environment`.
+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::
+
+    python3.8 -m venv ~/redenv
+
+And activate it with the following command::
+
+    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::
+
+    pyenv version
+
+Now, create a virtual environment with the following command::
+
+    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::
+
+    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:
 

docs/install_windows.rst

@@ -68,8 +68,35 @@ Manually installing dependencies
 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. See the section `installing-in-virtual-environment`.
+straightforward.
+
+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.
+
+Start with opening a command prompt (open Start, search for "command prompt", then click it)
+
+.. warning::
+
+    These commands will not work in PowerShell - you have to use command prompt as said above.
+
+Then create your virtual environment with the following command::
+
+    py -3.8 -m venv "%userprofile%\redenv"
+
+And activate it with the following command::
+
+    "%userprofile%\redenv\Scripts\activate.bat"
+
+.. important::
+
+    You must activate the virtual environment with the above command every time you open a new
+    Command Prompt to run, install or update Red.
 
 --------------
 Installing Red
@@ -78,8 +105,7 @@ Installing Red
 .. attention:: You may need to restart your computer after installing dependencies
                for the PATH changes to take effect.
 
-1. Open a command prompt (open Start, search for "command prompt", then click it)
+Run **one** of the following set of commands, depending on what extras you want installed
-2. Run **one** of the following set of commands, depending on what extras you want installed
 
   * Normal installation:
 

docs/venv_guide.rst

@@ -1,142 +0,0 @@
-.. _installing-in-virtual-environment:
-
-=======================================
-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)
-
-**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 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:
-
---------------
-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.
-
-~~~~~~~~~~~~~~~~~~~~~~~~
-``venv`` on Linux or Mac
-~~~~~~~~~~~~~~~~~~~~~~~~
-Create your virtual environment with the following command::
-
-    python3.8 -m venv ~/redenv
-
-And activate it with the following command::
-
-    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 reading `below <after-activating-virtual-environment>`.
-
-~~~~~~~~~~~~~~~~~~~
-``venv`` on Windows
-~~~~~~~~~~~~~~~~~~~
-Create your virtual environment with the following command::
-
-    py -3.8 -m venv %userprofile%\redenv
-
-And activate it with the following command::
-
-    %userprofile%\redenv\Scripts\activate.bat
-
-.. important::
-
-    You must activate the virtual environment with the above command every time you open a new
-    Command Prompt to run, install or update Red.
-
-Continue reading `below <after-activating-virtual-environment>`.
-
-.. _using-pyenv-virtualenv:
-
---------------------------
-Using ``pyenv virtualenv``
---------------------------
-
-.. note::
-
-    This is for non-Windows users only.
-
-Using ``pyenv virtualenv`` saves you the headache of remembering where you installed your virtual
-environments. If you haven't already, install pyenv with `pyenv-installer`_.
-
-First, ensure your pyenv interpreter is set to python 3.8.1 or greater with the following command::
-
-    pyenv version
-
-Now, create a virtual environment with the following command::
-
-    pyenv virtualenv <name>
-
-Replace ``<name>`` with whatever you like. If you forget what you named it, use the command ``pyenv
-versions``.
-
-Now activate your virtualenv with the following command::
-
-    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 reading `below <after-activating-virtual-environment>`.
-
-.. _pyenv-installer: https://github.com/pyenv/pyenv-installer/blob/master/README.rst
-
-----
-
-.. _after-activating-virtual-environment:
-
-Once activated, your ``PATH`` environment variable will be modified to use the virtual
-environment's python executables, as well as other executables like ``pip``.
-
-From here, install Red using the commands listed on your installation guide (`Windows
-<installing-red-windows>` or `Non-Windows <installing-red-linux-mac>`).
-
-.. note::
-
-    The alternative to activating the virtual environment each time you open a new shell is to
-    provide the full path to the executable. This will automatically use the virtual environment's
-    python interpreter and installed libraries.
-
---------------------------------------------
-Virtual Environments with Multiple Instances
---------------------------------------------
-If you are running multiple instances of Red on the same machine, you have the option of either
-using the same virtual environment for all of them, or creating separate ones.
-
-.. note::
-
-    This only applies for multiple instances of V3. If you are running a V2 instance as well,
-    You **must** use separate virtual environments.
-
-The advantages of using a *single* virtual environment for all of your V3 instances are:
-
-- When updating Red, you will only need to update it once for all instances (however you will still need to restart all instances for the changes to take effect)
-- It will save space on your hard drive
-
-On the other hand, you may wish to update each of your instances individually.
-
-.. important::
-
-    Windows users with multiple instances should create *separate* virtual environments, as
-    updating multiple running instances at once is likely to cause errors.