Include main examples readme in docs (#2448)

Author: quaquel

.gitignore

@@ -2,7 +2,8 @@
 benchmarks/**/*.pickle
 
 # exampledocs
-docs/examples/*.md
+docs/examples/*
+docs/example.md
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/conf.py

@@ -316,17 +316,20 @@ def setup_examples_pages():
     # create md files for all examples
     # check what examples exist
     examples_folder = osp.abspath(osp.join(HERE, "..", "mesa", "examples"))
-    basic_examples = [f.path for f in os.scandir(osp.join(examples_folder, "basic")) if f.is_dir() and not f.name.startswith("__") ]
-    advanced_examples = [f.path for f in os.scandir(osp.join(examples_folder, "advanced")) if f.is_dir() and not f.name.startswith("__")]
+    basic_examples = [("basic", f.path) for f in os.scandir(osp.join(examples_folder, "basic")) if f.is_dir() and not f.name.startswith("__") ]
+    advanced_examples = [("advanced", f.path) for f in os.scandir(osp.join(examples_folder, "advanced")) if f.is_dir() and not f.name.startswith("__")]
     examples = basic_examples + advanced_examples
 
     with open(os.path.join(HERE, "example_template.txt")) as fh:
         template = string.Template(fh.read())
 
-    pathlib.Path(os.path.join(HERE, "examples")).mkdir(parents=True, exist_ok=True)
+    root_folder = pathlib.Path(os.path.join(HERE, "examples"))
+    root_folder.mkdir(parents=True, exist_ok=True)
+    pathlib.Path(os.path.join(root_folder, "basic")).mkdir(parents=True, exist_ok=True)
+    pathlib.Path(os.path.join(root_folder, "advanced")).mkdir(parents=True, exist_ok=True)
 
     examples_md = []
-    for example in examples:
+    for kind, example in examples:
         base_name = os.path.basename(os.path.normpath(example))
 
         agent_filename = os.path.join(example, "agents.py")
@@ -337,17 +340,21 @@ def setup_examples_pages():
         md_filename = f"{base_name}.md"
         examples_md.append(base_name)
 
-        md_filepath = os.path.join(HERE, "examples", md_filename)
+        md_filepath = os.path.join(HERE, "examples", kind, md_filename)
         write_example_md_file(agent_filename, model_filename, readme_filename, app_filename, md_filepath, template)
 
     # create overview of examples.md
     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(
-                examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/{base_name}>" for base_name in examples_md]),
+                readme=readme_md,
+            #     examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/{base_name}>" for base_name in examples_md]),
             )
         )
         fh.write(content)

docs/examples.md

@@ -1,10 +1,3 @@
 
-# Examples
+$readme
 
-
-```{toctree}
-:maxdepth: 1
-
-$examples
-
-```

docs/examples_overview_template.txt

@@ -1,37 +1,37 @@
 # 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.
+These examples are a collection of classic agent based models built using Mesa. These core examples 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)
+### [Boltzmann Wealth Model](examples/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 Flockers Model](examples/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)
+### [Conway's Game of Life](examples/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)
+### [Schelling Segregation Model](examples/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)
+### [Virus on a Network Model](examples/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.
+### [Epstein Civil Violence Model](examples/advanced/epstein_civil_violence)
+Joshua Epstein's [model](https://www.pnas.org/doi/10.1073/pnas.092080199) 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)
+### [Demographic Prisoner's Dilemma on a Grid](examples/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)
+### [Sugarscape Model with Traders](examples/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)
+### [Wolf-Sheep Predation Model](examples/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.