Merge pull request #191 from jhlch/docs

Use reflow for maven site.

.gitignore

@@ -5,4 +5,4 @@ pom.xml.next
 release.properties
 *.iml
 .idea/
-dependency-reduced-pom.xml
+dependency-reduced-pom.xml

pom.xml

@@ -13,7 +13,9 @@
   the specific language governing permissions and limitations under the
   License.
 -->
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
 
   <groupId>com.cloudera.oryx</groupId>
@@ -517,7 +519,7 @@
               <id>enforce</id>
               <configuration>
                 <rules>
-                  <dependencyConvergence />
+                  <dependencyConvergence/>
                   <requireMavenVersion>
                     <version>3.2.1</version>
                   </requireMavenVersion>
@@ -728,6 +730,25 @@
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-site-plugin</artifactId>
           <version>3.4</version>
+          <dependencies>
+            <dependency>
+              <groupId>org.apache.maven.doxia</groupId>
+              <artifactId>doxia-module-markdown</artifactId>
+              <version>1.6</version>
+            </dependency>
+            <dependency>
+              <groupId>lt.velykis.maven.skins</groupId>
+              <artifactId>reflow-velocity-tools</artifactId>
+              <!--> Must depend on snapshot version for markdown to render correctly. <-->
+              <version>1.1.2-SNAPSHOT</version>
+            </dependency>
+            <!-- Reflow skin requires Velocity >= 1.7  -->
+            <dependency>
+              <groupId>org.apache.velocity</groupId>
+              <artifactId>velocity</artifactId>
+              <version>1.7</version>
+            </dependency>
+          </dependencies>
         </plugin>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
@@ -966,7 +987,8 @@
     applications on top of Spark, Spark Streaming and Kafka. On this, it provides further
     support for real-time, large scale machine learning, and end-to-end applications of
     this support for common machine learning use cases, like recommendations, clustering,
-    classification and regression.</description>
+    classification and regression.
+  </description>
   <url>https://github.com/OryxProject/oryx</url>
   <inceptionYear>2014</inceptionYear>
   <licenses>

src/site/markdown/contribute.md

@@ -0,0 +1,4 @@
+# Contribute
+
+* [Issues](https://github.com/OryxProject/oryx/issues/)
+* [Fork on GitHub](https://github.com/OryxProject/oryx/)

src/site/markdown/docs/api-end-pt-ref.md

@@ -0,0 +1,45 @@
+Javadoc
+=======
+
+See project [javadoc](http://oryxproject.github.io/oryx/apidocs/index.html).
+
+Bundled Serving Layer Apps
+==========================
+
+Oryx bundles several end-to-end applications, including a Serving Layer with REST endpoints.
+The bundled app endpoints are:
+
+Collaborative filtering / Recommendation
+----------------------------------------
+
+* [`/recommend`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/Recommend.html)
+* [`/recommendToMany`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/RecommendToMany.html)
+* [`/recommendToAnonymous`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/RecommendToAnonymous.html)
+* [`/similarity`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/Similarity.html)
+* [`/similarityToItem`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/SimilarityToItem.html)
+* [`/knownItems`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/KnownItems.html)
+* [`/estimate`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/Estimate.html)
+* [`/estimateForAnonymous`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/EstimateForAnonymous.html)
+* [`/because`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/Because.html)
+* [`/mostSurprising`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/MostSurprising.html)
+* [`/popularRepresentativeItems`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/PopularRepresentativeItems.html)
+* [`/mostPopularItems`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/MostPopularItems.html)
+* [`/mostActiveUsers`] (http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/MostActiveUsers.html)
+* [`/item/allIDs`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/AllItemIDs.html)
+* [`/ready`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/Ready.html)
+* [`/pref`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/Preference.html)
+* [`/ingest`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/als/Ingest.html)
+
+Classification / Regression
+---------------------------
+
+* [`/predict`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/rdf/Predict.html)
+* [`/classificationDistribution`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/rdf/ClassificationDistribution.html)
+* [`/train`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/rdf/Train.html)
+
+Clustering
+----------
+
+* [`/assign`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/kmeans/Assign.html)
+* [`/distanceToNearest`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/kmeans/DistanceToNearest.html)
+* [`/add`](http://oryxproject.github.io/oryx/apidocs/com/cloudera/oryx/app/serving/kmeans/Add.html)

src/site/markdown/docs/faq-and-troubleshooting.md

@@ -0,0 +1,8 @@
+## Tests show errors, but still pass?
+
+[This issue](https://github.com/OryxProject/oryx/issues/73) catalogs the problem. These seem
+to be ignorable errors that are attributable to the fact that a Zookeeper and Kafka process
+are started and stopped rapidly. Although this is done cleanly with some built-in waiting, it
+does not seem sufficient.
+
+There is likely a better answer but exceptions shown in the issue above can be ignored.

src/site/markdown/docs/how-to-release.md

@@ -0,0 +1,72 @@
+This will only be of interest to the project's maintainers!
+
+# Prerequisites
+
+This process requires that you have created a file called, for example, `private-settings.xml` which contains authentication credentials for pushing to the distribution repository. Example:
+
+```
+<?xml version="1.0"?>
+<settings>
+  <servers>
+    <server>
+      <id>oryx.repo</id>
+      <username>snapshots</username>
+      <password>...</password>
+    </server>
+    <server>
+      <id>oryx.snapshots.repo</id>
+      <username>snapshots</username>
+      <password>...</password>
+    </server>
+  </servers>
+</settings>
+```
+
+It also requires that you have the GPG key that is written into the project POM, and that you know its passphrase.
+
+# Releasing Maven Artifacts
+
+1. Clone `master` from the repo:
+`git clone https://github.com/OryxProject/oryx.git`
+
+1. If this is a fresh checkout, optionally configure your user name and email for use with git commits, if not already set globally:
+`git config user.name "Your Name"`
+`git config user.email "Your Email"`
+
+1. Double-check that tests pass and packaging succeeds first:
+`mvn clean package`
+
+1. Check for problems or errors first with `-DdryRun`. Consider skipping the (lengthy) tests in these steps with `-DskipTests` if they've been run already. To avoid answering the same question many times, the release and new development versions can be supplied on the command line:
+`mvn -Darguments="-DskipTests" -DdryRun -DreleaseVersion=... -DdevelopmentVersion=... release:prepare`
+
+1. Repeat the above without `-DdryRun`.
+
+1. Now perform the release. This will require the `gpg` passphrase for the GPG signing key specified in `pom.xml`:
+`mvn -s private-settings.xml -Darguments="-DskipTests -Dgpg.passphrase=..." release:perform`
+
+# Releasing Binaries
+
+1. To get the latest changes and tags post-build, `git pull --tags`
+1. Checkout the build tag for this build with `git checkout tags/...`
+1. `mvn -DskipTests clean package`
+1. Assembled binaries appear at `oryx-serving/target/oryx-serving-....jar` and likewise for `speed` and `batch`
+1. Navigate to the Github release that was just created, at `https://github.com/OryxProject/oryx/releases/tag/...`
+1. Edit the title to something more meaningful like `Oryx x.y.z`
+1. Paste brief release notes into the description, including a link to resolved issues for the associated milestone, usually of the form `https://github.com/OryxProject/oryx/issues?q=milestone%3A...+is%3Aclosed`
+1. Attach the Batch, Speed, and Serving layer binaries and save the updated release.
+
+# Updating the Site
+
+1. Using the repo above, checkout the release tag: `git checkout -f tags/...`
+1. `mvn clean site:site site:stage`
+1. In another location, checkout the site branch into a new directory `oryx-gh-pages`:
+`git clone -b gh-pages https://github.com/OryxProject/oryx.git oryx-gh-pages`
+You may need to set `user.name` and `user.email` as above if it's a fresh clone.
+1. `rm -r .../oryx-gh-pages/*`
+1. `cp -r target/staging/* .../oryx-gh-pages/`
+1. `cd .../oryx-gh-pages`
+1. `git add -A .`
+1. `git commit -m "Update site for ..."`
+1. `git push origin gh-pages`
+1. In a minute, check your work at http://oryxproject.github.io/oryx/
+1. Optionally delete the repo cloned above if no longer needed.