Include separate `examples` folder or `docs` folder

[jwhhh]

We need to keep a folder to include documentation + example notebooks (if any) for each contribution.

Option 1:

contrib/
|___ xxx_problem
        |___ README.md
        |___ examples
                |___ notebook_1.ipynb
                |___ notebook_2.ipynb
                |___ script.py
                |___ something.pdf
        |___ ... (other files)

Option 2:

contrib/
|___ xxx_problem
        |___ docs
                |___ README.md
                |___ notebook_1.ipynb
                |___ notebook_2.ipynb

The second option might be more natural if a contributor wants to link to a notebook as they explain something in the README file.

We also need to think about how to present / manage the display of the documentation + notebooks.

UPDATE: We can provide links to GitHub files; for ipynb, we can also provide links to binder / colab.

[jwhhh]

What do you think @valentineap ?

[valentineap]

I think the README file definitely belongs in the top-level directory - this is a fairly universal standard.

The broader question here is: how do we support users who wish to provide a richer documentation set? Our approach of requiring a README file that can be built into the documentation is aimed at guaranteeing some minimal amount of documentation for each example, but it obviously places limits on what can be (easily) done.

An examples/ folder is (at least) superficially attractive. It would be easy for us to auto-generate a list of all .ipynb files within this folder and minimally link these into the documentation as: "Here are some examples: [1] [2] [3]", but this will be fairly ugly. It would be better if we could build in a sentence or two about what each example shows: "[1] -- a demonstration of X [2] -- a demonstration of Y". However, it's going to be hard to do this programmatically. We could insist on contributors describing the examples in a yaml file or something, but it all starts getting rather complicated... Perhaps we could instead tell contributors to create an index.md file in the examples folder that has text+links and we use that.

Another possibility would be to allow users to (optionally) create a docs/ folder that gets built using something like the monorepo tool. This would enable them to provide a richer set of documentation than is possible using the README. I guess I envisage that if a docs/ folder exists, we would use that instead of trying to parse their README.

Thoughts? Perhaps we should hold off on any action for a few days -- I'm trying to do some work on docs at the moment.

[valentineap]

Once we're happy with #107 we can look at this.