Include main examples readme in docs

[quaquel]

This replaces the examples landing page on RTD with one directly based on the README.md file in the examples folder.

To make this work, I had to slightly change the links in the example headers. They don't work anymore on GitHub, but do work on RTD. I think this is a worthwhile tradeoff. If you read the readme on github, you have the file explorere at the top of the page anyway. I tested six or so versions of the links but none worked for both.

I updated the readme to reflect its use on RTD and fixes a broken link.

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 +2.5% [+1.1%, +4.1%]	🔵 +0.3% [+0.1%, +0.5%]
BoltzmannWealth	large	🔵 -0.3% [-0.7%, +0.0%]	🔵 +2.2% [+1.4%, +3.0%]
Schelling	small	🔵 -0.8% [-1.2%, -0.4%]	🔵 -0.2% [-0.5%, +0.1%]
Schelling	large	🔵 +0.5% [-0.2%, +1.2%]	🔵 +1.4% [-0.1%, +3.1%]
WolfSheep	small	🔵 -0.6% [-0.8%, -0.4%]	🔵 -0.2% [-0.5%, -0.0%]
WolfSheep	large	🔵 -0.2% [-1.6%, +1.4%]	🔵 -1.5% [-5.0%, +2.9%]
BoidFlockers	small	🔵 -0.6% [-1.2%, -0.0%]	🔵 -0.2% [-0.9%, +0.4%]
BoidFlockers	large	🔵 -1.0% [-1.5%, -0.6%]	🔵 -0.8% [-1.6%, -0.1%]

[EwoutH]

This is really awesome, this is so helpful for the Examples page, especially with the links. A really powerful experience!

[EwoutH]

One particular thing I find really weird about ReadTheDocs is the navigation, but we can figure that out in another time. This is a huge improvement already!

[quaquel]

One particular thing I find really weird about ReadTheDocs is the navigation, but we can figure that out in another time. This is a huge improvement already!

I agree. It partly depends on the theme that is used as specified in conf.py. Mesa uses the pydata theme. This is a 3 column layout: https://github.com/pydata/pydata-sphinx-theme. It would not surprise me if there are inconsistencies in how this theme is currently used in the mesa docs.

[quaquel]

One particular thing I find really weird about ReadTheDocs is the navigation, but we can figure that out in another time.

So I had a closer look at this. It seems that the left-hand column (Section navigation) is filled based on the presence or absence of a toctree. For example, for API this exists (docs/api/api_main.md). And because of this, a section natigation is created in the left-hand column. We had one, before this PR, for examples, and as a result, we had section navigation filled it.

A simple solution, therefore seems to be to divide up the docs a bit more into sections. An obvious brake down would be Overview, Getting Started (with tutorials, examples, migration guide, mesa packages, and best practices), and API docs. This would clear up the top row which is now overcrowded, and make the left hand side of the page more useful. @EwoutH, let me know what you thinks. This is a five-minute PR.

[EwoutH]

That might indeed work better than the current setup and give a clean UI.

If it’s a five minute PR, could you make it as draft so we can compare?