Use reflow for maven site.

[hougs]

I've switched the skin oryx uses to reflow. Reflow allows us to easily render markdown into html and steal nice looking themes from bootswatch. We can use any of the theme avaiable from bootswatch and configure the site using the site.xml file. It is kind of plain and has rough edges but I thought I would throw it out as a start to build on.

[srowen]

Does the site plugin need to be downgraded to 3.3?
Also it seems like Doxia has a 1.6 version now; might be worth using the latest.
Nit: the indentation of the XML here is deeper than the 2-space indent in the rest of the file.

[hougs]

Does Oryx use a 2 space indent and a 4 space overhang? I'll change the settings in my editor.

[srowen]

Yeah, I have been using 2-space indent everywhere.

[hougs]

This is pretty much grabbed verbatim and split across a few files. I mostly wanted content to fill in the site.

What sort of content do you think will help users get Oryx? The things the immediately spring to mind to me are:
Landing page

• What is Oryx?
  Documentation landing page
• Quick start
• Tutorial
• JavaDoc
• TestJavaDoc
  -Rest API References
• Link to Wiki [1]

[1] How much we want to duplicate or move documentation that is currently written on the wiki or in readmes is debatable. We could be more automated about it by having a docs making wrapper script that moves the readme.md into src/site/markdown before running mvn site. Or we could leave it where it is and produce all new content, some of which will have to be done anyway.

[srowen]

Yes, all of those things are good. Between the Github README.md and wikis, and the current site at http://oryxproject.github.io/oryx/ we have all of those I think. The question at the moment is how to prettify and centralize them better.

Although I think the README.md has to remain with some minimal info, it's fine if everything else moves to the site as-is. Editing the wiki pages is easier in that there is no need to republish the site, but, they don't change often and aren't versioned together as wikis, I suppose. I don't mind rebuilding the site once in a while.

If it's easier to start by just merging this and working from there, that's fine. We'll keep the wiki pages until they are replaced, and make a forwarding link for a while, before disabling them eventually.

[srowen]

Looks like this is on 1.6, FWIW

[srowen]

OK so would this PR then copy all the wiki markdown into the site? then we can shut off the wikis. Is that the idea?

[hougs]

This is done, with a minor caveat: Because of a markdown parsing bug, we need to rely on a snapshot version of the reflow maven plugin. So, building the docs currently requires having the reflow snapshot locally installed. I generated the new version of gh-pages. The look is different (which I wouldnt mind second eyes on.) and the version of the docs generated is 2.0.0-SNAPSHOT. Instead of having to generate the pages you can have a look at the style and layout of the site here. If it looks fine, I'll squash the commits and cherry pick on the latest released version to gen the docs.

[srowen]

Looking at the docs we have now, we have basically:

• The Maven-generated site
• The wikis
• The README.md overview on Github

The Maven generated site is pretty useless except for the javadoc, so it can all be replaced with this, sure. What about javadoc though? Is that still all magically built and integrated with mvn site?

Yes looks like this ports all the wikis straight over, check.

I'm conflicted about README.md. I really like having something, a 1-pager, for people to skim when they land on the Github site, which is still where people often go first. I don't want to duplicate that; I don't want to remove it entirely from Github either. Am I being irrational about this? Is the right move to retain a little info on README.md and the full version on the site? If so then the new site is OK and it's a question of chopping down README.md later when wikis are deleted.

For the site itself, it's looking fine. (Can we use a sans serif font -- is that easy to control?) What's under the "Documentation" tab is the important part. In fact I had envisioned, basically, a sidebar with a big list of the pages you see in Documentation and that's about it. Not even tabs at the top. Like http://kafka.apache.org/ for example. Is that easy? I don't want to turn you into a web designer, but hoping that the declarative site syntax (which I have never learned) might make that simple.

[hougs]

I think the README as it exists now is more than a one-pager. I do think that the best path forward it a shorter readme (that has depend on oryx with these maven coords section) and most of the meat-y docs on the website.

As for the font, it is probably easiest to choose from the precanned themes check them out and let me know which you like. I think a perma sidebar could be nice when you are in the docs subsection. In other sections, I think it may be distracting or strange. I'lll see how easy to is to apply there.

[srowen]

United looks like a nice theme!

By the way, is this all generated magically with mvn site still? with javadoc in there too? or is there any more to know about the process?

The site is basically all the docs subsection, so I suppose my proposal is: the entirety of the site is one docs subsection? Literally the list of wikis down the left, rendered in the middle. A la Kafka. It's simplistic but direct.

If that's not just a tiny bit of config, forget it. The site may really just have one tab, the docs tab, then. That's OK. To me that's about all the site needs to present, so as long as it's as directly accessible as possible that's good.

[hougs]

United it is. I've run the site goal, and it looks really nice.

I've reworked it so that a lot of the docs are on the same page. Some are still on separate pages, because there really are a lot, and some are short and somewhat tangential. I put all the pages that I thought had a good flow together into one. I also added a sidebar table of contents. It scrolls with the page.

As for deployment, we could add in this plugin to the mix. Anyone with push access and github creds configured in their settings.xml would need to be careful to run the goal site:site, and not the entire phase site, because running the entire phase triggers a docs deployment. What do you think?

[srowen]

Great, is there an easy way to see the result? I'm sure it's OK, mostly curious. It sounds like this ticks all the boxes -- still auto-generated, nice updated theme, gets the wiki content onto the site.

BTW I remember I made two tiny wiki changes since you likely started. If you don't get to them in this copy I can make the changes later.

diff --git a/API-Endpoint-Reference.md b/API-Endpoint-Reference.md
index 4bd70c7..c5f38fc 100644
--- a/API-Endpoint-Reference.md
+++ b/API-Endpoint-Reference.md
@@ -24,6 +24,7 @@ Collaborative filtering / Recommendation
 * [`/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)
diff --git a/Cluster-Setup.md b/Cluster-Setup.md
index 97dc0ae..a35625b 100644
--- a/Cluster-Setup.md
+++ b/Cluster-Setup.md
@@ -83,8 +83,7 @@ names of these topics are "OryxInput" and "OryxUpdate" respectively. They need t
 created before Oryx is started. 

 Each can default to have one partition, but more can be configured if much higher read
-throughput is needed. `oryx.batch.streaming.receiver-parallelism` and 
-`oryx.speed.streaming.receiver-parallelism` should then be increased to match. 
+throughput is needed.
 The example below shows 1 partition. Replication factor can be any value, but 3 is recommended.

Yes, I'd like to use an automated site deployment plugin. I can tackle that and try to get it working. The manual process is short but annoyingly automatable.

[hougs]

you can run mvn site then navigate to file:///${ORYX_HOME}/target/site/index.html in a bowser.

I've added the changes to my commit. I'll go ahead and push these changes to master and the new site to gh-pages!

[srowen]

Yeah I got that, just wondering if we could look at the current state of things as a preview. If there's anything else to be done I think we can just do it separately, so go ahead.