From 3991a2d88fbd6575d9c6e94bc986b1deabacad76 Mon Sep 17 00:00:00 2001 From: jack1142 <6032823+jack1142@users.noreply.github.com> Date: Fri, 14 Feb 2020 15:19:52 +0100 Subject: [PATCH] [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 | 39 ++++++++++ docs/index.rst | 2 +- docs/install_linux_mac.rst | 76 +++++++++++++++++++- docs/install_windows.rst | 32 ++++++++- docs/venv_guide.rst | 142 ------------------------------------- 5 files changed, 144 insertions(+), 147 deletions(-) create mode 100644 docs/about_venv.rst delete mode 100644 docs/venv_guide.rst diff --git a/docs/about_venv.rst b/docs/about_venv.rst new file mode 100644 index 000000000..1b10c0fc0 --- /dev/null +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 2a7a714dd..95dce9158 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/install_linux_mac.rst b/docs/install_linux_mac.rst index a4ab20cb0..6b7e20da5 100644 --- a/docs/install_linux_mac.rst +++ b/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 + +Replace ```` 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 + +.. 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: diff --git a/docs/install_windows.rst b/docs/install_windows.rst index 05e8c60d9..5ceeedfb0 100644 --- a/docs/install_windows.rst +++ b/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) -2. Run **one** of the following set of commands, depending on what extras you want installed +Run **one** of the following set of commands, depending on what extras you want installed * Normal installation: diff --git a/docs/venv_guide.rst b/docs/venv_guide.rst deleted file mode 100644 index dea83eee6..000000000 --- a/docs/venv_guide.rst +++ /dev/null @@ -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 `. - -~~~~~~~~~~~~~~~~~~~ -``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 `. - -.. _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 - -Replace ```` 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 - -.. 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 `. - -.. _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 -` or `Non-Windows `). - -.. 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.