Skip to content

Commit

Permalink
preliminary changes to the dev enviornment setup guide
Browse files Browse the repository at this point in the history
  • Loading branch information
benne238 committed May 4, 2021
1 parent ecbfbd6 commit 80ee836
Showing 1 changed file with 37 additions and 36 deletions.
73 changes: 37 additions & 36 deletions docs/Dev Environment Setup Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,6 @@ This document will walk you through the setup and configuration of a development
These are already installed on the provided development machines.

- [git](https://git-scm.com/downloads)
- [NodeJS](https://nodejs.org/en/) >= v14.11.0
- npm >= v6.14.8
- npx >= v6.14.8
- [Python](https://www.python.org/downloads/) == 3.6.9

## Configuring Your SSH Keys
Expand Down Expand Up @@ -182,17 +179,17 @@ Now go to [github.itap.purdue.edu/settings/keys](https://github.itap.purdue.edu/
## Cloning and Opening the Repository
Using the integrated terminal in VS Code, run:
```none
git clone git@github.itap.purdue.edu:ECN/webqueue2.git
git clone git@github.itap.purdue.edu:ECN/webqueue2-api.git
```
This will create a `webqueue2` folder in your user's home directory. Open this directory using the "Open Folder" button:
This will create a `webqueue2-api` folder in your user's home directory. Open this directory using the "Open Folder" button:

![Open Repo](images/Dev%20Environment%20Setup%20Guide/Open%20Repo.gif)

!!! note
VS Code will automatically reconnect to the last remote host used when it reopens.

!!! tip
If you need to reconnect manually, there will now be an option to open the webqueue2 folder directly from the Remote Hosts menu:
If you need to reconnect manually, there will now be an option to open the webqueue2-api folder directly from the Remote Hosts menu:

![Remote Folder Open](images/Dev%20Environment%20Setup%20Guide/Remote%20Folder%20Open.png)

Expand All @@ -207,11 +204,6 @@ There are three groups of plugins to install depending on what kind of developme
- [Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph) for a more detailed view of git info
- [Markdown Preview GitHub Styling](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles) for previewing Markdown as it will appear on GitHub

#### Frontend Extensions:
- [ES Lint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for JavaScript linting
- [Babel JavaScript](https://marketplace.visualstudio.com/items?itemName=mgmcdermott.vscode-language-babel) for JavaScript and JSX syntax highlighting and error checking
- [MDX](https://marketplace.visualstudio.com/items?itemName=silvenon.mdx) to provide MDX syntax support

#### Backend/API Extensions:
- [Python Docstring Generator](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) for generating Google style docstrings according to section 3.8 of [Google's Python style guide](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings)

Expand All @@ -222,7 +214,7 @@ The Python extension supports virtual environments but needs to be told where th

Create or modify the file `.vscode/settings.json` and add the following:
```none
"python.pythonPath": "./api/venv/bin/python3"
"python.pythonPath": "./venv/bin/python3"
```

!!! tip
Expand All @@ -242,33 +234,42 @@ At this point, your `.vscode/settings.json` file should look like this:
}
```

## Configuring Tools
Install npm dependencies:
```bash
npm install
## 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.

Run this code in the `webqueue2-api` directory to make a python virtual environment:
```none
python3 -m venv venv
```

Create the Python virtual environment:
```bash
npm run venv:create
Run this code to activate the virtual environment:
```none
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

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:
```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]`

## Using Tools
All of the tools in this project are accessible as an npm task so you can interact with them by running `npm run <task>`. The tasks are:
## 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.

| Task | Description |
### API Commands
| Command | Description |
| - | - |
| `frontend:start` | This will start a development server on [localhost:3000](http://localhost:3000). (If the server is on your local machine, this will also launch your default browser at that address.) As you save changes in the `public/` or `src/` directories you'll see your changes in the browser. (API requests are automatically proxied to the API server.) |
| `frontend:start:docs` | This will start a local server on [localhost:6060](http://localhost:6060) showing you the React component documentation. As you change a components documentation file in `/src/components/<component_name>/<component_name>.md` you'll see your changes in the browser.
| `frontend:build` | This will output a static bundle of the frontend in `build/` that can be put on any webserver. |
| `frontend:build:docs` | This will output a static bundle of the frontend documentation in `styleguidist/frontend-docs` that can be put on any webserver. |
| `frontend:kill` | Kills the runaway frontend process(es). |
| `frontend:kill:docs` | Kills the runaway frontend docs process(es). |
| `api:start` | This will start a local WSGI server on [localhost:5000](http://localhost:5000) to access the API. You can interact with the API using `curl` or [Postman](https://www.postman.com/) |
| `api:start:docs` | This will start a local server on [localhost:8000](http://localhost:8000) to access the API docs. As you change API documentation files in `api/documentation/docs` you'll see your changes in the browser. |
| `api:build:docs` | This will output a static bundle of the API documentation in `api/documentation/site` that can be put on any webserver. |
| `api:kill` | Kills the runaway API process(es). |
| `api:kill:docs` | Kills the runaway API docs process(es). |
| `venv:create` | This will create a virtual environment in `api/venv` and install requirements from `api/requirements.txt`. |
| `venv:delete` | This will delete the folder `api/venv`. |
| `venv:reset` | This will run `venv:delete` then `venv:create`. |
| `python3 -m webqueue2_api start-api` | This will start a local WSGI server on [localhost:5000](http://localhost:5000) to access the API. You can interact with the API using `curl` or [Postman](https://www.postman.com/) |
| `python3 -m webqueue2_api stop-api` | Kills the runaway API process(es). |
| `mkdocs serve` | This will start a local server on [localhost:8000](http://localhost:8000) to access the API docs. As you change API documentation files in `api/documentation/docs` you'll see your changes in the browser. |
| `mkdocs build` | This will output a static bundle of the API documentation in `webqueue2-api/site` that can be put on any webserver. |

0 comments on commit 80ee836

Please sign in to comment.