Update documents for 0.9

[benblack86]

Currently we have docs on this branch: https://github.com/tumblr/colossus/tree/gh-pages-source

@DanSimon did you have any ideas around how to handle docs for 0.8 and 0.9? Should we just keep docs for 0.9?

[DanSimon]

I think we can keep docs for both. Lots of projects will have links to the same docs for older versions (like how Akka does here), but going forward we probably won't need to update the 0.8 docs any further.

[benblack86]

I'll have a look around to see how other projects handle this. I'm thinking we will probably want to get rid of the gh-pages-source branch and instead have a colossus-docs sub project, so the docs can be versioned with the rest of the colossus project.

[benblack86]

I think we should move to paradox for generating the docs. It is owned by our favorite company and is used for akka docs. The main reason I think it is is great is that you can link to real code snippets. Therefore, you will know if the code is wrong as it wouldn't compile.

I'd have a colossus-docs sub project, which is versioned with the rest of the code. So in our case, master would point at 0.8 docs, and develop would point at 0.9 docs. After compiling (sbt paradox) we would have to copy the compiled site to a versioned directory in gh-pages branch. We can either have an index.html file in the root, which would list all versions available, or we could symlink to everything in the latest version. Obviously, we should automate all this like the way the docs are uploaded using the current rake task.

I put together a very basic example: https://github.com/benblack86/doc-testing (see the master branch for source files, and then gh-pages for the output). The site is at https://benblack86.github.io/doc-testing. In this example, I've gone for an index.html file in the root that links to the versions available (obviously it should be styled like the latest docs, but that would have to be done by hand). I've also created a latest directory that is symlinked to 0.9 so you can have the address https://benblack86.github.io/doc-testing/latest/index.html.

An alternative would be to use http://docs.readthedocs.io/, but it seems that might show ads on the sidebar (at least for some themes) and they don't provide the killer snippet code feature.

cc @aliyakamercan @jlbelmonte @amotamed @dxuhuang

[benblack86]

Done