Improves docs2

Replaces #789, rebased against devel branch.

By default github targeted the master branch. @Araq can you change the repo settings to use devel as the default branch?