documenting self-contained examples

[d-v-b]

We should have a dedicated section in our docs page for the self-contained examples in the examples folder.
We should also ensure that these examples are self-documenting as much as possible, and I think the best solution there is to put each example in its own directory, and to include a README.md file along with the source code. The content of the readme can be re-used in our rendered docs.

[d-v-b]

closed by #3502