Skip to content

Commit

Permalink
Add more details about virtual environment setup
Browse files Browse the repository at this point in the history
  • Loading branch information
campb303 committed May 18, 2021
1 parent 9f3f413 commit 485de8a
Showing 1 changed file with 25 additions and 11 deletions.
36 changes: 25 additions & 11 deletions docs/Dev Environment Setup Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 485de8a

Please sign in to comment.