Example usages in API documentation

[matt-graham]

The package has API documentation automatically generated from docstrings using Sphinx. This currently provides high-level descriptions and details of arguments and returned values for all public facing functions.

To reduce the barrier to entry for new users and provide more context for how the different functions provided by the package can be used, we should add examples illustrating usage patterns to all public functions. These examples should also be structured as doctests to ensure they remain up to date and to provide additional test coverage for the package.