Update documentation and examples

[lteacher]

Details
As usual before I release the next massive set of changes, all the documentation needs to be updated.

This is a placeholder to act as a reminder.