Migrate Dev Environment Setup Guide to mkdocs

api/documentation/docs/Dev Environment Setup Guide.md

@@ -0,0 +1,271 @@
+# Dev Environment Setup Guide
+This document will walk you through the setup and configuration of a development environment for webqueue2 using the provided development machines, SSH authentication, GitHub and VS Code.
+
+## Prerequisites
+
+### On Your Computer
+- [VS Code](https://code.visualstudio.com/download)
+- [Cisco AnyConnect for WebVPN](https://webvpn.purdue.edu/)
+
+### On The Development Computer
+
+!!! Note
+    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
+We will be using SSH keys to authenticate to both the development machines and GitHub.
+
+In either PowerShell on Windows or bash on macOS/Linux, run the following command and accept all defaults by pressing <kbd>Enter</kbd>:
+```none
+ssh-keygen
+```
+This will create the files `id_rsa` and `id_rsa.pub` in the `.ssh` folder inside your user's folder. Your user's folder can usually be found at:
+
+=== "Windows"
+    ```none
+    C:\Users\<user_name>
+    ```
+=== "macOS"
+    ```none
+    /Users/<user_name>
+    ```
+=== "Linux"
+    ```none
+    /home/<user_name>
+    ```
+
+Most CLI shells like PowerShell and bash use the <kbd> ~ </kbd> (tilda) key as a shortcut for your user's folder.
+
+You can confirm these files were created by running:
+```none
+ls ~/.ssh/
+```
+
+## Configuring SSH
+In your editor of choice, create the file `~/.ssh/config` and add this:
+
+!!! tip
+    Replace `campb303` with your career account username and replace `w2vm1` with the name of the provided development machine you're connecting to.
+
+```none
+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
+```
+
+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.                      |
+| LocalForward | Forwards a port on your computer to a port on the computer you're connecting to. |
+
+!!! tip
+    You need to be connected to WebVPN before SSH'ing into a the development machine.
+
+To test your configuration, run `ssh` followed by the `Host` value. When prompted for your password, enter your career account password and press <kbd>Enter</kbd>.
+
+!!! warning
+    Most shell environemnts like PowerShell and bash do not show your password being typed but it is being typed.
+
+For the configuration above you would run:
+
+```none
+ssh campb303-w2vm1
+campb303@w2vm1's password:
+```
+
+## Adding SSH Keys
+Now that we've generated SSH keys and configured our host entries, we need to add our SSH key to the host. This will allow us to connect to these machines without passwords later.
+
+!!! tip
+    Replace `HOST` below with the value from above. _Example:_ `campb303-w2vm1`
+
+=== "PowerShell on Windows"
+    ```powershell
+    type $env:USERPROFILE\.ssh\id_rsa.pub | ssh HOST "cat >> .ssh/authorized_keys"
+    ```
+=== "bash on macOS/Linux"
+    ```bash
+    ssh-copy-id HOST
+    ```
+
+If the key was added successfully, you can login without entering a password by running:
+```
+ssh HOST
+```
+
+## Installing VS Code
+Download and install [VS Code](https://code.visualstudio.com/download). Be sure to add `code` to your PATH.
+
+=== "Windows"
+
+    Adding `code` to your PATH on Windows is a checkbox in the installer:
+
+    ![VS Code Install Options on Windows](https://i0.wp.com/www.techomoro.com/wp-content/uploads/2019/06/5.jpg?w=596&ssl=1)
+
+    _Image from [this article on Techomoro](https://www.techomoro.com/installing-visual-studio-code-on-windows-10/)_
+
+=== "macOS/Linux"
+
+    Adding `code` to your PATH on macOS/Linux is accessible by searching for "PATH" in the Command Pallete. You can access the Command Pallete with the keyboard shortcut <kbd>Command</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>:
+
+    ![VS Code Install Options on macOS/Linux](https://i.stack.imgur.com/Ng886.png)
+
+    _Image from [this StackOverflow thread](https://stackoverflow.com/questions/30065227/run-open-vscode-from-mac-terminal)_
+
+## Connecting To The Development Machine
+Install the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) plugin. After installation a new icon will appear in the sidebar:
+
+![Remote SSH Plugin Icon](images/Dev%20Environment%20Setup%20Guide/Remote%20SSH%20Icon.png)
+
+- Click on the Remote SSH icon and you'll see the SSH host you just defined
+- Select the host and click the New Window icon to connect. A new window connected to that host will appear
+
+!!! note
+    This may take a couple of minutes on the first connection while VS Code installs its server.
+
+![Remote SSH Connection Example](images/Dev%20Environment%20Setup%20Guide/Connect%20to%20Remote%20SSH%20Host.gif)
+
+If prompted for a platform, select Linux:
+![VS Code Select Platform](images/Dev%20Environment%20Setup%20Guide/VS%20Code%20Select%20Platform.png)
+
+## Adding Your SSH Keys to GitHub
+Because the development machine will be the computer that connects to GitHub, we need to create another SSH key and add it to our GitHub profile:
+
+First, open VS Code's integrated terminal by pressing <kbd>Control</kbd> + <kbd>~</kbd> (tilda)
+
+![Open VS Code's integrated terminal](images/Dev%20Environment Setup%20Guide/Open%20VS%20Code%20Integrated%20Terminal.gif)
+
+Now run the following command and accept all defaults by pressing <kbd>Enter</kbd>:
+```bash
+ssh-keygen
+```
+
+This will create the files `id_rsa` and `id_rsa.pub` in `~/.ssh/`. You can confirm this by running:
+```bash
+ls ~/.ssh/
+```
+
+Now copy the public key from `id_rsa.pub` by openning the file in VS Code, selecting its contents and copying it. You can open the file in VS Code by running the following in the integrated terminal:
+
+!!! danger
+    Do not copy your private key from `id_rsa`! This key should never leave your machine.
+
+```bash
+code ~/.ssh/id_rsa.pub
+```
+
+Now go to [github.itap.purdue.edu/settings/keys](https://github.itap.purdue.edu/settings/keys). You may be prompted to login using your career account username and password.
+
+- Click the "New SSH Key" button
+- Give the key a title that tells you what device the key is from (e.g. Desktop or Dev Machine)
+- Paste the contents of `id_rsa.pub` into the key box
+- Click the "Add SSH Key" button
+
+![Add SSH Key to GitHub](images/Dev%20Environment%20Setup%20Guide/Add%20SSH%20Key%20to%20GitHub.gif)
+
+## Cloning and Opening the Repository
+Using the integrated terminal in VS Code, run:
+```none
+git clone git@github.itap.purdue.edu:ECN/webqueue2.git
+```
+This will create a `webqueue2` 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:
+
+    ![Remote Folder Open](images/Dev%20Environment%20Setup%20Guide/Remote%20Folder%20Open.png)
+
+## 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
+- [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)
+
+### Configuring Extensions
+
+#### Python
+The Python extension supports virtual environments but needs to be told where the virtual environment is.
+
+Create or modify the file `.vscode/settings.json` and add the following:
+```none
+"python.pythonPath": "./api/venv/bin/python3"
+```
+
+!!! tip
+    The Python extension may complain and tell you to select another interpreter. Ignore this warning for now.
+
+#### Python Docstring Generator
+For consistentcy, we'll use a docstring template. Create or modify the file `.vscode/settings.json` and add the following:
+```none
+"autoDocstring.customTemplatePath": "./docstring-format.mustache"
+```
+
+At this point, your `.vscode/settings.json` file should look like this:
+```none
+{
+    "python.pythonPath": "./api/venv/bin/python3",
+    "autoDocstring.customTemplatePath": "./docstring-format.mustache"
+}
+```
+
+## Configuring Tools
+Install npm dependencies:
+```bash
+npm install
+```
+
+Create the Python virtual environment:
+```bash
+npm run venv:create
+```
+
+## 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:
+
+| Task | Description |
+| - | - |
+| `kill:api` | Kills the runaway API process(es). |
+| `kill:frontend` | Kills the runaway frontend process(es). |
+| `venv:freeze` | Regenerates the API requirements.txt file and mitigates [this pip bug](https://github.com/pypa/pip/issues/4022). |
+| `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`. |
+| `build:docs` | This will output a static bundle of the frontend documentation in `styleguidist/frontend-docs` that can be put on any webserver. |
+| `build:frontend` | This will output a static bundle of the frontend in `build/` that can be put on any webserver. |
+| `venv:reset` | This will run `venv:delete` then `venv:create`. |
+| `start:frontend` | 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.) |
+| `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/) |
+| `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.

api/documentation/mkdocs.yml

@@ -13,7 +13,8 @@ markdown_extensions:
   - admonition
   - pymdownx.details
   - pymdownx.superfences
-  - pymdownx.highlight
+  - pymdownx.highlight:
+      use_pygments: false
   - pymdownx.inlinehilite
   - pymdownx.tabbed
   - pymdownx.emoji:
@@ -36,6 +37,8 @@ markdown_extensions:
 theme:
   name: material
   palette:
+    # Used to toggle dark mode.
+    # scheme: slate
     primary: deep purple
     accent: teal
   icon: