Add source for hollow docs (#212)

Also create deployment shell script to automate updates.
The script still needs to be run manually, for now.

.gitignore

@@ -9,3 +9,4 @@
 **.iml
 **.iws
 .idea
+venv

deploy_docs.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# Simple script to deploy the doc site. Note that this will run the mkdocs generator
+# and then directly push to github.
+if ! type virtualenv &> /dev/null; then
+  echo "virtualenv is required: easy_install virtualenv"
+  exit 0
+fi
+if ! type pip &> /dev/null; then
+  echo "pip is required: easy_install pip"
+  exit 0
+fi
+if [ ! -f 'mkdocs.yml' ]; then
+  echo "Please run this command from the repository root"
+  exit 0
+fi
+virtualenv venv
+source venv/bin/activate
+pip install -r requirements.txt
+mkdocs gh-deploy
+rm -r site

docs/CNAME

@@ -0,0 +1 @@
+hollow.how

docs/OSSMETADATA

@@ -0,0 +1 @@
+osslifecycle=active

docs/acknowledgements.md

@@ -0,0 +1,20 @@
+Hollow is originally created by Drew Koszewnik with the advice and support of fellow members of the Data Platform Technologies team at Netflix:
+
+* David Su
+* Deva Jayaraman
+* Jatin Shah
+* Kinesh Satiya
+* Lavanya Kanchanapalli
+* Ramin Forood
+* Rohit Kaul
+* Tim Taylor
+
+Hollow is maintained by the Data Platform Technologies team at Netflix.
+
+Hollow makes use of an [implementation](https://github.com/yonik/java_util/blob/master/src/util/hash/MurmurHash3.java) of the MurmurHash3 algorithm authored by Yonik Seeley.
+
+Hollow makes use of Thomas Wang's well known 32-bit mix function, which is based on an original suggestion by Robert Jenkins.
+
+The _hollow-diff-ui_ object diff view was inspired in part by Chas Emerick's [jsdifflib](http://github.com/cemerick/jsdifflib), and borrows some of the .css from that project.
+
+This documentation was created with [MkDocs](http://www.mkdocs.org), using a theme from [material](https://github.com/Netflix/hollow).

docs/community.md

@@ -0,0 +1,33 @@
+# Getting Support
+
+For bug reports and feature requests, please file a [GitHub issue](https://github.com/Netflix/hollow/issues).  
+
+If you have a question that isn't covered in this documentation, please reach out for help either on Stack Overflow or [Gitter](https://gitter.im/Netflix/hollow)
+
+## Stack Overflow
+
+The Platform Data Technologies team at Netflix will monitor posts tagged with `hollow`.
+
+## Gitter
+
+The Platform Data Technologies team at Netflix is often available for chat via [Gitter](https://gitter.im/Netflix/hollow).  We hope that you'll stick around and pay it forward by answering other users' questions when they arise.
+
+# Contributing to Hollow
+
+We'll gladly review and accept pull requests for Hollow.  If you want to have a design discussion for your changes, please reach out to us on Gitter.
+
+## Backwards Compatibility
+
+New features in Hollow should always be added in a way that is backwards compatible, except in _extremely_ rare cases when a major version is released.
+
+If you would like to make a contribution which breaks backwards compatibility, please contact us so we can evaluate alternate ways to achieve the desired result, and/or whether to schedule the change for an upcoming major version release.
+
+## Dependencies
+
+The core project _hollow_ should have zero `compile` dependencies, and should only depend on one library (jUnit) as a `test` dependency.  We believe this provides long-term stability for users, reduces licensing concerns, and eliminates the possibility that _other_ project dependencies will be compiled against incompatible versions of dependent libraries.
+
+If you would like to make a contribution which requires a third-party dependency, please contact us before proceeding so we can discuss the appropriate location for the addition.
+
+## sun.misc.Unsafe
+
+The core project *hollow* utilizes `sun.misc.Unsafe`. Your IDE may treat this as an error. See [Issue #5](https://github.com/Netflix/hollow/issues/5) for how to compile without errors.

docs/data-ingestion.md

@@ -0,0 +1,154 @@
+# Data Ingestion
+
+Hollow includes a few ready-made data ingestion mechanisms.  Additionally, custom data ingestion mechanisms can be created relatively easily using the [Low Level Input API](advanced-topics.md#low-level-input-api).
+
+## HollowObjectMapper
+
+When using a `HollowProducer`, each call to `state.add(obj)` is delegated to a `HollowObjectMapper`.  The `HollowObjectMapper` is used to add POJOs into a `HollowWriteStateEngine`:
+
+```java
+HollowWriteStateEngine engine = /// a state engine
+HollowObjectMapper mapper = new HollowObjectMapper(writeEngine);
+
+for(Movie movie : movies)
+    writeEngine.add(movie);
+```
+
+The `HollowObjectMapper` can also be used to initialize the data model of a `HollowWriteStateEngine` without adding any actual data:
+```java
+HollowWriteStateEngine engine = /// a state engine
+HollowObjectMapper mapper = new HollowObjectMapper(writeEngine);
+
+mapper.initializeTypeState(Movie.class);
+mapper.initializeTypeState(Show.class);
+```
+
+Schemas will be assumed based on the field and type names in the POJOs.  Any referenced types will also be traversed and included in the derived data model.
+
+!!! hint "Thread Safety"
+    The `HollowObjectMapper` is thread-safe; multiple threads may add Objects at the same time.
+
+### Specifying type names in the HollowObjectMapper
+
+By default, type names are equal to the names of classes added to the `HollowObjectMapper`.  Alternatively, the name of a type may be explicitly defined by using the `@HollowTypeName` annotation.  This annotation can be added at either the class or field level.
+
+The following example `Award` class will reference a type `AwardName`, which will contain a single string value:
+```java
+public class Award {
+    long id;
+
+    @HollowTypeName(name="AwardName")
+    String name;
+}
+```
+
+The following example `Category` class will be added as the type `Genre`, where not otherwise specified by referencing fields:
+```java
+@HollowTypeName(name="Genre")
+public class Category {
+   ...
+}
+```
+
+!!! note "Namespaced fields"
+    Using the `@HollowTypeName` attribute is a convenient way to add appropriate [record type namespacing](data-modeling.md#namespaced-record-type-names) into your data model.
+
+### Inlining fields in the HollowObjectMapper
+
+You can [inline](data-modeling.md#inlined-vs-referenced-fields) fields in the `HollowObjectMapper` by annotating them with `@HollowInline`.  The following example `Creator` class inlines the field `creatorName`:
+
+```java
+public class Creator {
+    long id;
+
+    @HollowInline
+    String creatorName;
+}
+```
+
+The following `java.lang.*` types can be inlined:
+
+* `String`
+* `Boolean`
+* `Integer`
+* `Long`
+* `Double`
+* `Float`
+* `Short`
+* `Byte`
+* `Character`
+
+### Memoizing POJOs in the HollowObjectMapper
+
+If a long field named `__assigned_ordinal` is defined in a POJO class, then `HollowObjectMapper` will use this field to record the assigned ordinal when Objects of this class are added to the state engine.  
+
+When the `HollowObjectMapper` sees this POJO again, it will short-circuit writing to the state engine and discovering or assigning an ordinal -- it will instead return the previously recorded ordinal.  If during processing you can reuse duplicate referenced POJOs, then you can use this effect to greatly speed up adding records to the state engine.
+
+If the `__assigned_ordinal` field is present, it should be initialized to -1.  The field may be (but does not have to be) private and/or final.
+
+The following example `Director` class uses the `__assigned_ordinal` optimization:
+```java
+public class Director {
+    long id;
+    String directorName;
+
+    private final int __assigned_ordinal = -1L;
+}
+
+```
+
+!!! warning
+    If the `__assigned_ordinal` optimization is used, POJOs should _not be modified_ after they are added to the state engine.  Any modifications after the first time a memoized POJO is added to the state engine will be ignored and any references to these POJOs will always point to the _originally_ added record.
+
+
+## JSON to Hollow
+
+The project _hollow-jsonadapter_ contains a component which will automatically parse json into a `HollowWriteStateEngine`.  The expected format of the json will be defined by the schemas in the `HollowWriteStateEngine`.  The data model must be pre-initialized.  See the [Schema Parser](advanced-topics.md#schema-parser) topic in this document for an easy way to configure the schemas with a text document.
+
+The `HollowJsonAdapter` class is used to populate records of a single type from a json file.  A single record:
+```json
+{
+  "id": 1,
+  "releaseYear": 1999,
+  "actors": [
+     {
+        "id": 101,
+        "actorName": "Keanu Reeves"
+     },
+     {
+        "id": 102,
+        "actorName": "Laurence Fishburne"
+     }
+  ]
+}
+```
+
+Can be parsed with the following code:
+```java
+String json = /// the record above
+
+HollowJsonAdapter jsonAdapter = new HollowJsonAdapter(writeEngine, "Movie");
+
+jsonAdapter.processRecord(json);
+```
+
+If a field defined in the schema is not encountered in the json data, the value will be null in the corresponding Hollow record.  If a field is encountered in the json data which is not defined in the schema, the field will be ignored.
+
+A large number of records in a single file can also be processed:
+```java
+Reader reader = /// a reader for the json file
+
+HollowJsonAdapter jsonAdapter = new HollowJsonAdapter(writeEngine, "Movie");
+
+jsonAdapter.populate(reader);
+```
+
+When processing an entire file, it is expected that the file contains only a single json array of records of the expected type.  The records will be processed in parallel.
+
+!!! hint "Hollow to JSON"
+    Hollow objects can be converted to JSON string using `HollowRecordJsonStringifier`. Tools backed by Hollow data is one of the cases where this can be useful.
+
+
+## Zeno to Hollow
+
+The project _hollow-zenoadapter_ has an adapter which can be used with Hollow’s predecessor, Zeno.  We used this as part of our migration path from Zeno to Hollow, and it is provided for current users of Zeno who would like to migrate to Hollow as well.  Start with the _HollowStateEngineCreator_.