From 485de8a661dcf3cd320677e7f8a0665a5aeed688 Mon Sep 17 00:00:00 2001
From: Justin Campbell <campb303@purdue.edu>
Date: Tue, 18 May 2021 12:08:27 -0400
Subject: [PATCH] Add more details about virtual environment setup

---
 docs/Dev Environment Setup Guide.md | 36 ++++++++++++++++++++---------
 1 file changed, 25 insertions(+), 11 deletions(-)

diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md
index a040d16..bf6d441 100644
--- a/docs/Dev Environment Setup Guide.md	
+++ b/docs/Dev Environment Setup Guide.md	
@@ -247,33 +247,47 @@ At this point, your `.vscode/settings.json` file should look like this:
 ```
 
 ## Setting Up the Virtual Environment
-To be able to make edits to the api and be able to immediately test them, create and checkout to the branch where you will make edits.
+For development, we'll use a [Python Virtual Environment](https://realpython.com/python-virtual-environments-a-primer/) to isolate out changes and have a reproducible dev environment.
 
-Run this code in the `webqueue2-api` directory to make a python virtual environment:
-```none
+In VS Code's integrated terminal:
+
+Create a virtual environment at `./venv/`:
+```bash
 python3 -m venv venv 
 ```
 
-Run this code to activate the virtual environment:
-```none
+Activate the virtual environment:
+```bash
 source venv/bin/activate
 ```
+
 !!! tip
-    To deactivate the python virtual environment without removing the `venv` directory, simply enter the command `deactivate` while in an active python virtual environment
+    To deactivate the virtual environment and use your system's Python interpreter, run:
+
+    ```bash
+    deactivate
+    ```
 
 Update pip within the virtual environment:
 ```none
 pip install -U pip
 ```
-!!! tip
-    At this point, the most recent version of pip should be installed, not version 9.0.1
 
-Install all of the dependencies for the api and the api itself:
+Install the webqueue2 API within the virtual environemt:
 ```none
 pip install -e .[all]
 ```
-!!! tip
-    `[all]` will install all the dependencies for working with the api and for creating and viewing documentation with mkdocs. If you want to install just the api wihtout the documentation dependencies, replace `[all]` with `[dev]`. If you want to install just the documentation dependencies without installing the api and its dependencies, replace `[all]` with `[docs]`
+
+`-e` installs a package in [editable mode](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-e) which allows code changes to take effect without reinstalling a package.
+
+webqueue2 API has multiple [conditional dependencies](https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#id7):
+
+| Condition | Installation Command | Description |
+| - | - | - |
+| Production | `pip install webqueue2-api` | For use in production. Only installed needed packages. |
+| Development | `pip install webqueue2-api[dev]` | For use in development. Installs everything for production and extra packages for development. |
+| Documentation | `pip install webqueue2-api[docs]` | For use in creating documentation. Installs everything for production and extra packages for documentation. |
+| All | `pip install webqueue2-api[all]` | A shortcut for installing production, development and documentation dependencies. |
 
 ## Using the dev Tools
 There are two main tools for development, mkdocs is used for viewing and building documentation while webqueue2-api is used for running the api and testing changes made to the code.