doc updates
address chris' issues
Merge pull request #117 from brack3t/fix/docs

Cleaner docs, more examples, better cross-linking.