RBM docs and fixes (WIP)

This is still a work in progress but I'm sending you the PR to avoid duplication of work. If you want to work on this before I finish, please merge this, but if not, there's no hurry, wait for me to finish the docs.

The PR is huge, but if you merge master into your branch, only the last 5-ish commits from me should remain.

Thanks a lot for the contribution and I hope I can help!