From 80ee836b3465a1d6205869cf2ff307455ce79b60 Mon Sep 17 00:00:00 2001 From: benne238 Date: Tue, 4 May 2021 16:09:34 -0400 Subject: [PATCH 01/14] 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 From da4fbb1318cb44627b4805d6c1b15981712d1f02 Mon Sep 17 00:00:00 2001 From: benne238 Date: Fri, 7 May 2021 13:39:28 -0400 Subject: [PATCH 02/14] making docs preliminary docs --- docs/api/making-docs.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/api/making-docs.md diff --git a/docs/api/making-docs.md b/docs/api/making-docs.md new file mode 100644 index 0000000..0e2ee6b --- /dev/null +++ b/docs/api/making-docs.md @@ -0,0 +1,10 @@ +## Making Docs + +The api documentation uses mkdocs to create documenation, which is based in markdown. + +All of the doucmentation can be found in the `docs` directory in the `webqueue2-api` repo, and all of the api specific documentation can be found in the `docs/api` directory. + + +## Mkdocs configuration + +A basic version of mkdocs can be installed by using `pip install mkdocs`, however, this is not recomened as the current implementation makes use of several plugins that enahance the basic features of mkdocs. To install all of the dependencies for this, follow the steps for setting up the dev environment. \ No newline at end of file From c41325c2f9b80a52a6ff714f0dfd428b63a987d5 Mon Sep 17 00:00:00 2001 From: benne238 Date: Fri, 7 May 2021 13:39:44 -0400 Subject: [PATCH 03/14] preliminary package structure docs --- docs/package-structure.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/package-structure.md diff --git a/docs/package-structure.md b/docs/package-structure.md new file mode 100644 index 0000000..c88ff85 --- /dev/null +++ b/docs/package-structure.md @@ -0,0 +1,30 @@ +## API package structure + +The api can be broken down into 4 distinct parts: +1. The logger +2. The api +3. The ECNQueue +4. The initialization scripts + +### Logger + +The logger is its own subpackage and script which is used for outputting log information to both the terminal and a specified file. The logger uses the logging module to create log outputs with specified format. + +### API + +The api is the link between the ECNQueue and the frontend. The api continuously runs in the background, and takes urls matching a specified format from the front end and translates those as functions to be executed in the ECNQueue. The api uses flask and flask restful to do this + +### ECNQueue + +The ECNQueue subpackage is a parser in the backend for all of the items in stored in the queue directory. The ECNQueue parses the text documents in the queue and outputs structured json, which is then transfered to the fronted via the api. + +### The initialization scripts + +The initialization scripts take in user input (either via command line or wrapper script) and initialize the logger, ECNQueue, and API according to the user input. After initializing and implementing all of the necessary configurations, the initialization scripts start the api. These scripts use argparse to get user input and subprocess to launch the api via gunicorn. While not its own subpackage, the scripts are located directly in the `webqueue2_api` directory. + + +## Structure + +```none + +``` \ No newline at end of file From a8b8eae81fbbcff077e0ae99665eab09cf0e2d5c Mon Sep 17 00:00:00 2001 From: benne238 Date: Fri, 7 May 2021 15:51:39 -0400 Subject: [PATCH 04/14] package structure diagram for the docs --- docs/package-structure.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/package-structure.md b/docs/package-structure.md index c88ff85..e2450bb 100644 --- a/docs/package-structure.md +++ b/docs/package-structure.md @@ -26,5 +26,38 @@ The initialization scripts take in user input (either via command line or wrappe ## Structure ```none - +webqueue2_api/ # webqueue2_api parent package +│ +├── api/ # api subpackage +│ ├── __init__.py +│ ├── auth.py +│ └── resources/ +│ ├── __init__.py +│ ├── item.py +│ ├── login.py +│ ├── queue.py +│ ├── queue_list.py +│ └── refresh_access_token.py +│ +├── ECNQueue/ # ecnqueue subpackge +│ ├── __init__.py +│ ├── Item.py +│ ├── parser/ +│ │ ├── __init__.py +│ │ └── parser.py +│ ├── Queue.py +│ └── utils.py +│ +├── logger/ # logger subpackage +│ └─── __init__.py +│ +├── utils/ # utils subpackage +│ ├── __init__.py +│ └── tree.py +│ +├── __init__.py +├── __main__.py # parses user input +├── global_configs.py # stores the config file location +├── start.py # returns a flask object ater initializing the user configs +└── validate_arguments.py # validates all of teh user passed arguments ``` \ No newline at end of file From 6b9721f88683f7ad3bebeb5fee2fc4d428a8d9b8 Mon Sep 17 00:00:00 2001 From: benne238 Date: Tue, 18 May 2021 08:52:12 -0400 Subject: [PATCH 05/14] migrate docstring format file from frontend --- docstring-format.mustache | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docstring-format.mustache diff --git a/docstring-format.mustache b/docstring-format.mustache new file mode 100644 index 0000000..7fc2a20 --- /dev/null +++ b/docstring-format.mustache @@ -0,0 +1,38 @@ +{{! Google Docstring Template }} +{{summaryPlaceholder}} + +{{extendedSummaryPlaceholder}} + +Example: + [example] + +{{#parametersExist}} +Args: +{{#args}} + {{var}} ({{typePlaceholder}}): {{descriptionPlaceholder}} +{{/args}} +{{#kwargs}} + {{var}} ({{typePlaceholder}}, optional): {{descriptionPlaceholder}}. Defaults to {{&default}}. +{{/kwargs}} +{{/parametersExist}} + +{{#exceptionsExist}} +Raises: +{{#exceptions}} + {{type}}: {{descriptionPlaceholder}} +{{/exceptions}} +{{/exceptionsExist}} + +{{#returnsExist}} +Returns: +{{#returns}} + {{typePlaceholder}}: {{descriptionPlaceholder}} +{{/returns}} +{{/returnsExist}} + +{{#yieldsExist}} +Yields: +{{#yields}} + {{typePlaceholder}}: {{descriptionPlaceholder}} +{{/yields}} +{{/yieldsExist}} \ No newline at end of file From 82b7e95acde6b4fd28da7e5d5b12b13d8e8bd897 Mon Sep 17 00:00:00 2001 From: benne238 Date: Tue, 18 May 2021 09:07:37 -0400 Subject: [PATCH 06/14] add dev environment to nav --- docs/Dev Environment Setup Guide.md | 2 +- docs/awesome-pages.yaml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index 6fc2fc8..b8a029e 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -229,7 +229,7 @@ For consistentcy, we'll use a docstring template. Create or modify the file `.vs At this point, your `.vscode/settings.json` file should look like this: ```none { - "python.pythonPath": "./api/venv/bin/python3", + "python.pythonPath": "./venv/bin/python3", "autoDocstring.customTemplatePath": "./docstring-format.mustache" } ``` diff --git a/docs/awesome-pages.yaml b/docs/awesome-pages.yaml index 0e8234b..5e7d488 100644 --- a/docs/awesome-pages.yaml +++ b/docs/awesome-pages.yaml @@ -2,4 +2,5 @@ # See: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin nav: - index.md + - 'Dev Environment Setup Guide.md' - API: api \ No newline at end of file From c78973cca62f24cb73d81e2ee0c27f44c992a58b Mon Sep 17 00:00:00 2001 From: benne238 Date: Tue, 18 May 2021 09:15:21 -0400 Subject: [PATCH 07/14] added restart to list of api commands --- docs/Dev Environment Setup Guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index b8a029e..c5fd1be 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -271,5 +271,6 @@ There are two main tools for development, mkdocs is used for viewing and buildin | - | - | | `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). | +| `python3 -m webqueue2_api restart-api` | Runs `python3 -m webqueue2_api stop-api` then `python3 -m webqueue2_api start-api` | | `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 From 824a5a7739a11fb3f9794b178cd1c3a852a73c0a Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Tue, 18 May 2021 11:08:52 -0400 Subject: [PATCH 08/14] Add note admonition for tilda usage in shells --- docs/Dev Environment Setup Guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index c5fd1be..e6465bc 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -37,7 +37,8 @@ This will create the files `id_rsa` and `id_rsa.pub` in the `.ssh` folder inside /home/ ``` -Most CLI shells like PowerShell and bash use the ~ (tilda) key as a shortcut for your user's folder. +!!! note + Most CLI shells like PowerShell and bash use the ~ (tilda) key as a shortcut for your user's folder. You can confirm these files were created by running: ```none From 22179e8ee5d3a5462d19e35f50ae86d883a5aea5 Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Tue, 18 May 2021 11:10:57 -0400 Subject: [PATCH 09/14] Update ssh config ports --- docs/Dev Environment Setup Guide.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index e6465bc..a6e4ca8 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -55,12 +55,10 @@ In your editor of choice, create the file `~/.ssh/config` and add this: Host campb303-w2vm1 HostName w2vm1.ecn.purdue.edu User campb303 - # Forward webqueue2 Frontend Port - LocalForward 3000 localhost:3000 # Forward webqueue2 API Port LocalForward 5000 localhost:5000 - # Forward webqueue2 Docs Port - LocalForward 6060 localhost:6060 + # Forward webqueue2 API Docs Port + LocalForward 8000 localhost:8000 ``` The configuration above will allow you to connect to the development machine and automatically forward ports for development tools to work. Here's a bit more detail about what's going on: From fd52b947462c22cff01cface62bd3d3cabc9b53d Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Tue, 18 May 2021 11:13:52 -0400 Subject: [PATCH 10/14] Remove unneccesary table padding --- docs/Dev Environment Setup Guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index a6e4ca8..4dd212d 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -63,11 +63,11 @@ Host campb303-w2vm1 The configuration above will allow you to connect to the development machine and automatically forward ports for development tools to work. Here's a bit more detail about what's going on: -| Key | Value | -|--------------|----------------------------------------------------------------------------------| -| Host | A friendly name to identify an SSH host by. This can be anything. | -| HostName | The DNS name or IP address of the computer you're connecting to. | -| User | The name of your user on the computer you're connecting to. | +| Key | Value | +| - | - | +| Host | A friendly name to identify an SSH host by. This can be anything. | +| HostName | The DNS name or IP address of the computer you're connecting to. | +| User | The name of your user on the computer you're connecting to. | | LocalForward | Forwards a port on your computer to a port on the computer you're connecting to. | !!! tip From de344251b13fe5f3cd012d7d4d368ef6d0fa65ea Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Tue, 18 May 2021 11:36:40 -0400 Subject: [PATCH 11/14] Add tip for SSH proxy jump hosts --- docs/Dev Environment Setup Guide.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index 4dd212d..481e503 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -69,9 +69,28 @@ The configuration above will allow you to connect to the development machine and | HostName | The DNS name or IP address of the computer you're connecting to. | | User | The name of your user on the computer you're connecting to. | | LocalForward | Forwards a port on your computer to a port on the computer you're connecting to. | + +Development machines are not publicly accessible. You'll need to be connected to WebVPN to connect to them. -!!! tip - You need to be connected to WebVPN before SSH'ing into a the development machine. +??? tip "SSH Jump Hosts" + WebVPN works on all platforms but requires an extra step to get to work. On macOS/Linux, `pier.ecn.purdue.edu` can be used as an [SSH jump host](https://www.tecmint.com/access-linux-server-using-a-jump-host/) allowing for development machines to be connected to automatically when openning VS Code. + + Assuming you already have an SSH key configured for `pier.ecn.purdue.edu`, you can use a jump host by adding the following to `~/.ssh/config`: + + ``` + Host campb303-pier + HostName pier.ecn.purdue.edu + User campb303 + + Host campb303-w2vm1 + HostName w2vm1.ecn.purdue.edu + ProxyJump campb303-pier + User campb303 + # Forward webqueue2 API Port + LocalForward 5000 localhost:5000 + # Forward webqueue2 API Docs Port + LocalForward 8000 localhost:8000 + ``` To test your configuration, run `ssh` followed by the `Host` value. When prompted for your password, enter your career account password and press Enter. From 9f3f4139be811d20a588efe2f5de71c374cf1f69 Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Tue, 18 May 2021 11:44:55 -0400 Subject: [PATCH 12/14] Simplify extensions list --- docs/Dev Environment Setup Guide.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index 481e503..a040d16 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -214,15 +214,9 @@ This will create a `webqueue2-api` folder in your user's home directory. Open th ## Configuring VS Code ### Installing Extensions -There are three groups of plugins to install depending on what kind of development you're doing: - -#### General plugins, (needed by everyone): - -- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) for working with Python virtual environments and debugging +- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) for Python language support, IntelliSense, virtual environments and debugging - [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 - -#### 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) ### Configuring Extensions From 485de8a661dcf3cd320677e7f8a0665a5aeed688 Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Tue, 18 May 2021 12:08:27 -0400 Subject: [PATCH 13/14] 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. From 1fddf8e8e61e95d9ad7fede46f7e0c905b6b6733 Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Tue, 18 May 2021 12:14:25 -0400 Subject: [PATCH 14/14] Correct and simplify API commands --- docs/Dev Environment Setup Guide.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/Dev Environment Setup Guide.md b/docs/Dev Environment Setup Guide.md index bf6d441..6ae7118 100644 --- a/docs/Dev Environment Setup Guide.md +++ b/docs/Dev Environment Setup Guide.md @@ -289,14 +289,11 @@ webqueue2 API has multiple [conditional dependencies](https://setuptools.readthe | 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. - ### API Commands | Command | Description | | - | - | -| `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). | -| `python3 -m webqueue2_api restart-api` | Runs `python3 -m webqueue2_api stop-api` then `python3 -m webqueue2_api start-api` | -| `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 +| `python3 -m webqueue2_api start-api` | Starts the API on [localhost:5000](http://localhost:5000). See [Getting Started](./api/Getting Started.md) for more info. | +| `python3 -m webqueue2_api stop-api` | Stops the API. | +| `python3 -m webqueue2_api restart-api` | Stops and starts the API. | +| `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 `./docs/` you'll see your changes in the browser. | +| `mkdocs build` | This will output a static bundle of the API documentation in `./site/` that can be put on any webserver. | \ No newline at end of file