From 80ee836b3465a1d6205869cf2ff307455ce79b60 Mon Sep 17 00:00:00 2001 From: benne238 Date: Tue, 4 May 2021 16:09:34 -0400 Subject: [PATCH] preliminary changes to the dev enviornment setup guide --- docs/Dev Environment Setup Guide.md | 73 +++++++++++++++-------------- 1 file changed, 37 insertions(+), 36 deletions(-) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index 43d36b8..6fc2fc8 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -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 @@ -182,9 +179,9 @@ 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) @@ -192,7 +189,7 @@ This will create a `webqueue2` folder in your user's home directory. Open this d 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) @@ -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) @@ -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 @@ -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 `. 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//.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`. | \ No newline at end of file +| `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. | \ No newline at end of file