add JS testing framework and "vendor" libraries (#61)

* readme and contributing docs laying out testing and local development
* don't load vendor JS libraries from external sources - "vendor" them into the project, allowing us to include running them in the test runner
* set up nodejs project structure: package.json file including task runners and dependencies. Basic smoke tests for charts.js. Karma test runner configuration for running in headless chrome.
* Have jekyll exclude hosting readme, gitignore, node dependencies and project bits.

CONTRIBUTING.md

@@ -12,7 +12,9 @@ In general, contributors should develop on branches based off of `master` and pu
 
 1. [Fork](https://github.com/Autodesk/hubble/fork) and clone the repository.
 1. Create a new branch based on `master`: `git checkout -b <my-branch-name> master`.
-1. Make your changes, add tests, and make sure the tests still pass (as soon as we have a testing framework :smiley:).
+1. Make your changes, add tests, and make sure the tests still pass.
+  - Changes to the web app (i.e. anything under `docs/`) can be validated by [running the web app tests](docs/README.md#tests).
+  - Changes to the updater component (i.e. anything under `updater/`) can't be validated yet, since we need a test suite there :).
 1. Push to your fork and [submit a pull request](https://github.com/Autodesk/hubble/compare) from your branch to `master`.
 1. Pat yourself on the back and wait for your pull request to be reviewed.
 

README.md

@@ -19,8 +19,8 @@ Explore our [interactive demo](https://autodesk.github.io/hubble/) or watch the
 ## Getting Started
 
 Hubble Enterprise consists of two components.
-The **updater** component queries relevant data from a GitHub Enterprise appliance and stores the results in a Git repository once a day.
-The **docs** component visualizes the collected data with [GitHub Pages](https://pages.github.com/).
+The **updater** component is a Python script that queries relevant data from a GitHub Enterprise appliance and stores the results in a Git repository once a day. Check out its [README.md](updater/README.md) for more details.
+The **docs** component is a web application that visualizes the collected data and is hosted with [GitHub Pages](https://pages.github.com/). Check out its [README.md](docs/README.md) for more details.
 
 1. Create a new, initialized, public repository for Hubble’s data on your GitHub Enterprise appliance (for instance, `https://git.company.com/scm/hubble-data`).
 1. Publish Hubble’s [data repository on GitHub Pages](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages).

docs/.gitignore

@@ -2,3 +2,6 @@ _site
 
 # You can clone your "hubble-data" repository to this location for debugging
 hubble-data
+
+# nodejs bits
+node_modules

docs/README.md

@@ -0,0 +1,42 @@
+## Hubble Web Application
+
+This web application is built as a [Jekyll](https://jekyllrb.com/) site and is intended to be hosted using [GitHub Pages](https://pages.github.com/).
+
+## Overview
+
+### Charts
+
+Each `.html` page in this directory contains one or more charts. Each chart is defined as an `<svg>` element with a few special attributes that define their behaviour:
+
+1. a `data-url` attribute referencing a `.tsv` file generated by the [updater component](../updater/README.md) - this is a relative URL that directs the chart where to ask for data from.
+1. a `class` attribute defining the kind of chart that will be rendered. Acceptable values are `chart`, `table`, and `collaboration`.
+1. a `data-type` _only applicable if the `class` is set to `chart`_; attribute referencing the sub-type of chart that will be rendered. Acceptable values are `history` and `list`.
+
+For details on how each kind of chart is rendered, take a look at the [`charts.js` file](assets/js/charts.js).
+
+## Development
+
+To run the site locally, you will need to install [Jekyll](https://jekyllrb.com/). Then change the `_config.yml` file and set the `dataURL` to `http://127.0.0.1:4000/demo-data`. Finally, run `jekyll serve`,
+and load http://127.0.0.1:4000 in your browser.
+
+## Tests
+
+This web application uses a framework called [Karma](https://karma-runner.github.io) as a test runner (a way to run JavaScript in different browser contexts), and [Jasmine](https://jasmine.github.io)
+as the testing / assertion library. The tests are implemented as `.js` files under the `spec/` folder, and as much as possible mirror the filenames of JavaScript source files.
+
+### Requirements
+
+- You will need a recent version of [node.js](https://nodejs.org) installed.
+- The tests run in a headless instance of the **Google Chrome** browser, so you will need a recent version of Google Chrome installed.
+- Install any needed dependencies by running `npm install` from this folder.
+
+### Running the Tests
+
+To run the tests once:
+
+    $ npm test
+
+During local development, it may be nice to keep the test runner running in the background as one makes changes to the JavaScript source files (under `assets/js/`), or the test files (under `spec/`) so as to
+get immediate feedback. This mode will re-run the tests every time a source or test file changes. To run in this mode:
+
+    $ npm test -- --no-single-run --auto-watch

docs/_config.yml

@@ -1 +1,2 @@
 dataURL: https://autodesk.github.io/hubble/demo-data
+exclude: ['spec', 'node_modules', 'README.md', '.gitignore', 'package.json', 'package-lock.json']

docs/_layouts/default.html

@@ -22,11 +22,11 @@
 		<link rel="stylesheet" type="text/css" href="{{ site.baseurl }}/assets/css/normalize.css?version=7c4fcab" media="screen">
 		<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Open+Sans:400,400i,700,700i" media="screen">
 		<link rel="stylesheet" type="text/css" href="{{ site.baseurl }}/assets/css/stylesheet.css?version=df12dbc" media="screen">
-		<script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
-		<script src="https://d3js.org/d3.v4.min.js"></script>
-		<script src="https://momentjs.com/downloads/moment-with-locales.min.js"></script>
-		<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.7.1/Chart.min.js"></script>
-		<script src="https://cdnjs.cloudflare.com/ajax/libs/spin.js/2.3.2/spin.min.js"></script>
+		<script src="{{ site.baseurl }}/assets/js/vendor/jquery-3.2.1.min.js"></script>
+		<script src="{{ site.baseurl }}/assets/js/vendor/d3.v4.min.js"></script>
+		<script src="{{ site.baseurl }}/assets/js/vendor/moment-with-locales.min.js"></script>
+		<script src="{{ site.baseurl }}/assets/js/vendor/Chart-2.7.1.min.js"></script>
+		<script src="{{ site.baseurl }}/assets/js/vendor/spin-2.3.2.min.js"></script>
 		<script src="{{ site.baseurl }}/assets/js/charts.js?version=1ff0187"></script>
 	</head>
 	<body>