testing main examples readme

docs/conf.py

@@ -344,9 +344,13 @@ def setup_examples_pages():
     with open(os.path.join(HERE, "examples_overview_template.txt")) as fh:
         template = string.Template(fh.read())
 
+    with open(os.path.join(examples_folder, "README.MD")) as fh:
+        readme_md = fh.read()
+
     with open(os.path.join(HERE, "examples.md"), "w") as fh:
         content = template.substitute(
             dict(
+                readme=readme_md,
                 examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/{base_name}>" for base_name in examples_md]),
             )
         )

docs/examples.md

@@ -1,6 +1,44 @@
 
 # Examples
 
+# Mesa core examples
+This folder contains a collection of example models built using Mesa. These core models are maintained by the Mesa team and are intended to demonstrate the capabilities of Mesa.
+
+More user examples and showcases can be found in the [mesa-examples](https://github.com/projectmesa/mesa-examples) repository.
+
+## Basic Examples
+The basic examples are relatively simple and only use stable Mesa features. They are good starting points for learning how to use Mesa.
+
+### [Boltzmann Wealth Model](basic/boltzmann_wealth_model)
+Completed code to go along with the [tutorial](https://mesa.readthedocs.io/latest/tutorials/intro_tutorial.html) on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
+
+### [Boids Flockers Model](basic/boid_flockers)
+[Boids](https://en.wikipedia.org/wiki/Boids)-style flocking model, demonstrating the use of agents moving through a continuous space following direction vectors.
+
+### [Conway's Game of Life](basic/conways_game_of_life)
+Implementation of [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life), a cellular automata where simple rules can give rise to complex patterns.
+
+### [Schelling Segregation Model](basic/schelling)
+Mesa implementation of the classic [Schelling segregation](http://nifty.stanford.edu/2014/mccown-schelling-model-segregation/) model.
+
+### [Virus on a Network Model](basic/virus_on_network)
+This model is based on the NetLogo [Virus on a Network](https://ccl.northwestern.edu/netlogo/models/VirusonaNetwork) model.
+
+## Advanced Examples
+The advanced examples are more complex and may use experimental Mesa features. They are good starting points for learning how to build more complex models.
+
+### [Epstein Civil Violence Model](advanced/epstein_civil_violence)
+Joshua Epstein's [model](http://www.uvm.edu/~pdodds/files/papers/others/2002/epstein2002a.pdf) of how a decentralized uprising can be suppressed or reach a critical mass of support.
+
+### [Demographic Prisoner's Dilemma on a Grid](advanced/pd_grid)
+Grid-based demographic prisoner's dilemma model, demonstrating how simple rules can lead to the emergence of widespread cooperation -- and how a model activation regime can change its outcome.
+
+### [Sugarscape Model with Traders](advanced/sugarscape_g1mt)
+This is Epstein & Axtell's Sugarscape model with Traders, a detailed description is in Chapter four of *Growing Artificial Societies: Social Science from the Bottom Up (1996)*. The model shows how emergent price equilibrium can happen via decentralized dynamics.
+
+### [Wolf-Sheep Predation Model](advanced/wolf_sheep)
+Implementation of an ecological model of predation and reproduction, based on the NetLogo [Wolf Sheep Predation](http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation) model.
+
 
 ```{toctree}
 :maxdepth: 1
@@ -10,5 +48,9 @@ virus on network </examples/virus_on_network>
 conways game of life </examples/conways_game_of_life>
 schelling </examples/schelling>
 boltzmann wealth model </examples/boltzmann_wealth_model>
+sugarscape g1mt </examples/sugarscape_g1mt>
+wolf sheep </examples/wolf_sheep>
+pd grid </examples/pd_grid>
+epstein civil violence </examples/epstein_civil_violence>
 
 ```

docs/examples_overview_template.txt

@@ -1,6 +1,8 @@
 
 # Examples
 
+$readme
+
 
 ```{toctree}
 :maxdepth: 1