Fixes and minor additions to the docs.
merged branch javiereguiluz/doc_fixes (PR #982)

This PR was merged into the master branch.

Commits
-------

aac6cb6 Fixes and minor additions to the docs.

Discussion
----------

Fixes and minor additions to the docs.