add examples to the docs
copying a test here for isolated debug