Improve awx/ui/README.md

awx/ui/README.md

@@ -1,68 +1,81 @@
-### Table of Contents
+# Ansible Tower UI
 
-1. [Requirements](#requirements)
+## Requirements
-2. [Usage](#usage)
-3. [Testing](#testing)
-4. [Adding new dependencies](#deps)
-5. [Using libraries without modular exports/depedency management](#polyfill)
-6. [Environment configuration](#environment)
-7. [NPM scripts](#scripts)
 
-### <a name="requirements">Requirements</a>
+### Node / NPM
+
+Tower currently requires the 6.x LTS version of Node and NPM.
+
+macOS installer: [https://nodejs.org/dist/latest-v6.x/node-v6.9.4.pkg](https://nodejs.org/dist/latest-v6.x/node-v6.9.4.pkg)
+
+RHEL / CentOS / Fedora:
 
-* A supported version of node + npm, constrained in `package.json`.
-```json
-"engines": {
-  "node": "^6.3.1",
-  "npm": "^3.10.3"
-}
 ```
-* C/C++ compiler tools, like GCC. Bundled in [Command Line Tools for Xcode](https://developer.apple.com/xcode/)
+$ curl --silent --location https://rpm.nodesource.com/setup_6.x | bash -
-* [node-gyp](https://github.com/nodejs/node-gyp)
+$ yum install nodejs
-```
-npm install -g node-gyp
 ```
 
-### <a name="usage">Usage</a>
+### Other Dependencies
 
-The following Makefile targets are available from the root dir of `ansible-tower`
+On macOS, install the Command Line Tools:
 
-**Native Docker**
+```
-Specify the container ID of a `tools_tower` instance.
+$ xcode-select --install
-`DOCKER_CID=containerID make ui-docker-cid`
+```
 
-**Docker Machine**
+RHEL / CentOS / Fedora:
-Specify the name of a docker-machine.
-`DOCKER_MACHINE_NAME=default make ui-docker-machine`
 
-Build a minified/uglified **release candidate**
+```
-`make ui-release`
+$ yum install bzip2 gcc-c++ git make
+```
 
-### <a name="testing">Testing</a>
+## Usage
+
+### Starting the UI
+
+First, the Tower API will need to be running. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+When using Docker for Mac or native Docker on Linux:
+
+```
+$ make ui-docker
+```
+
+When using Docker Machine:
+
+```
+$ DOCKER_MACHINE_NAME=default make ui-docker-machine
+```
+
+### Running Tests
 
 Run unit tests locally, poll for changes to both source and test files, launch tests in supported browser engines:
-`make ui-test`
+
+```
+$ make ui-test
+```
 
 Run unit tests in a CI environment (Jenkins)
-`make ui-test-ci`
 
-Run Protractor (E2E) tests in Saucelabs:
+```
-`make ui-test-saucelabs`
+$ make ui-test-ci
+```
 
-### <a name="deps">Adding new dependencies</a>
+### Adding new dependencies
 
-From the root dir of `ansible-tower`:
 
-#### Add/update a bundled vendor dependency
+#### Add / update a bundled vendor dependency
+
 1. `npm install --prefix awx/ui --save some-frontend-package@1.2.3`
 2. Add `'some-package'` to `var vendorFiles` in `./grunt-tasks/webpack.js`
 3. `npm  --prefix awx/ui shrinkwrap` to freeze current dependency resolution
 
-#### Add/update a dependecy in the build/test pipeline:
+#### Add / update a dependecy in the build/test pipeline
+
 1. `npm install --prefix awx/ui --save-dev some-toolchain-package@1.2.3`
 2. `npm  --prefix awx/ui shrinkwrap` to freeze current dependency resolution
 
-### <a name="polyfill">Polyfills, shims, patches</a>
+### Polyfills, shims, patches
 
 The Webpack pipeline will prefer module patterns in this order: CommonJS, AMD, UMD. For a comparison of supported patterns, refer to [https://webpack.github.io/docs/comparison.html](Webpack's docs).
 
@@ -74,6 +87,7 @@ Some javascript libraries do not export their contents as a module, or depend on
 // Tower source code depends on the lodash library being available as _
 _.uniq([1,2,3,1]) // will throw error undefined
 ```
+
 ```js
 // webpack.config.js
 plugins: [
@@ -82,6 +96,7 @@ plugins: [
   })
 ]
 ```
+
 ```js
 // the following requirement is inserted by webpack at build time
 var _ = require('lodash');
@@ -89,12 +104,12 @@ _.uniq([1,2,3,1])
 ```
 
 2. Use [`imports-loader`](https://webpack.github.io/docs/shimming-modules.html#importing) to inject requirements into the namespace of vendor code at import time. Use [`exports-loader`](https://webpack.github.io/docs/shimming-modules.html#exporting) to conventionally export vendor code lacking a conventional export pattern.
-3.  [Apply a functional patch](https://gist.github.com/leigh-johnson/070159d3fd780d6d8da6e13625234bb3). A webpack plugin is the correct choice for a functional patch if your patch needs to access events in a build's lifecycle. A webpack loader is preferable if you need to compile and export a custom pattern of library modules.
+3. [Apply a functional patch](https://gist.github.com/leigh-johnson/070159d3fd780d6d8da6e13625234bb3). A webpack plugin is the correct choice for a functional patch if your patch needs to access events in a build's lifecycle. A webpack loader is preferable if you need to compile and export a custom pattern of library modules.
-4.  [Submit patches to libraries without modular exports](https://github.com/leigh-johnson/ngToast/commit/fea95bb34d27687e414619b4f72c11735d909f93) - the internet will thank you
+4. [Submit patches to libraries without modular exports](https://github.com/leigh-johnson/ngToast/commit/fea95bb34d27687e414619b4f72c11735d909f93) - the internet will thank you
 
 Some javascript libraries might only get one module pattern right.
 
-### <a name="environment">Environment configuration</a> - used in development/test builds
+### Environment configuration - used in development / test builds
 
 Build tasks are parameterized with environment variables.
 
@@ -113,28 +128,30 @@ Environment variables can accessed in a Javascript via `PROCESS.env`.
 Example usage in `npm run build-docker-machine`:
 
 ```bash
-docker-machine ssh $DOCKER_MACHINE_NAME -f -N -L ${npm_package_config_websocket_port}:localhost:${npm_package_config_websocket_port}; ip=$(docker-machine ip $DOCKER_MACHINE_NAME); echo npm set ansible-tower:django_host ${ip}; grunt dev
+$ docker-machine ssh $DOCKER_MACHINE_NAME -f -N -L ${npm_package_config_websocket_port}:localhost:${npm_package_config_websocket_port}; ip=$(docker-machine ip $DOCKER_MACHINE_NAME); echo npm set ansible-tower:django_host ${ip}; $ grunt dev
 ```
 
 Example usage in an `npm test` script target:
 
-```bash
+```
 npm_package_config_websocket_port=mock_websocket_port npm_package_config_django_port=mock_api_port npm_package_config_django_host=mock_api_host npm run test:someMockIntegration
 ```
 
 You'll usually want to pipe and set vars prior to running a script target:
-```bash
+```
-npm set ansible-tower:websocket_host ${mock_host}; npm run script-name
+$ npm set ansible-tower:websocket_host ${mock_host}; npm run script-name
 ```
 
-### <a name="scripts">NPM Scripts</a>
+### NPM Scripts
 
 Examples:
 ```json
-  "scripts": {
+  {
-    "pretest": "echo I run immediately before 'npm test' executes",
+    "scripts": {
-    "posttest": "echo I run immediately after 'npm test' exits",
+      "pretest": "echo I run immediately before 'npm test' executes",
-    "test": "karma start karma.conf.js"
+      "posttest": "echo I run immediately after 'npm test' exits",
+      "test": "karma start karma.conf.js"
+    }
   }
 ```