Include examples in readthedocs (port)

.gitignore

@@ -1,6 +1,9 @@
 # Benchmarking
 benchmarks/**/*.pickle
 
+# exampledocs
+docs/examples/*.md
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

docs/README.md

@@ -1,15 +1,14 @@
-Docs for Mesa
-=============
+# Docs for Mesa
 
 The readable version of the docs is hosted at [mesa.readthedocs.org](http://mesa.readthedocs.org/).
 
 This folder contains the docs that build the docs for the core mesa code on readthdocs.
 
-### How to publish updates to the docs
+## How to publish updates to the docs
 
 Updating docs can be confusing. Here are the basic setups.
 
-##### Submit a pull request with updates
+#### Submit a pull request with updates
 1. Create branch (either via branching or fork of repo) -- try to use a descriptive name.
     * `git checkout -b doc-updates`
 1. Update the docs. Save.
@@ -23,7 +22,7 @@ Updating docs can be confusing. Here are the basic setups.
     * `git push origin doc-updates`
 1. From here you will want to submit a pull request to main.
 
-##### Update read the docs
+#### Update read the docs
 
 From this point, you will need to find someone that has access to readthedocs. Currently, that is [@jackiekazil](https://github.com/jackiekazil), [@rht](https://github.com/rht), and [@tpike3](https://github.com/dmasad).
 

docs/apis/experimental.md

@@ -3,11 +3,6 @@ This namespace contains experimental features. These are under development, and
 
 ## Cell Space
 
-```{eval-rst}
-.. automodule:: experimental.cell_space.__init__
-   :members:
-```
-
 ```{eval-rst}
 .. automodule:: experimental.cell_space.cell
    :members:
@@ -40,11 +35,6 @@ This namespace contains experimental features. These are under development, and
 
 ## Devs
 
-```{eval-rst}
-.. automodule:: experimental.devs.__init__
-   :members:
-```
-
 ```{eval-rst}
 .. automodule:: experimental.devs.eventlist
    :members:

docs/conf.py

@@ -14,12 +14,16 @@
 # serve to show the default.
 
 import os
+import os.path as osp
+import pathlib
 import sys
+import string
 from datetime import date
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
+HERE = osp.abspath(osp.dirname(__file__))
 sys.path.insert(0, os.path.abspath("."))
 sys.path.insert(0, "../examples")
 sys.path.insert(0, "../mesa")
@@ -289,3 +293,69 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+
+
+def write_example_md_file(agent_filename, model_filename, readme_filename, app_filename, md_filepath, template):
+    with open(agent_filename) as content_file:
+        agent_file = content_file.read()
+    with open(model_filename) as content_file:
+        model_file = content_file.read()
+    with open(readme_filename) as content_file:
+        readme_file = content_file.read()
+    with open(app_filename) as content_file:
+        app_file = content_file.read()
+
+    with open(md_filepath, "w") as fh:
+        content = template.substitute(
+            dict(agent_file=agent_file, model_file=model_file,
+                 readme_file=readme_file, app_file=app_file)
+        )
+        fh.write(content)
+
+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 = []  # fixme [f.path for f in os.scandir(osp.join(examples_folder, "advanced")) if f.is_dir()]
+    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)
+
+    examples_md = []
+    for example in examples:
+        base_name = os.path.basename(os.path.normpath(example))
+
+        agent_filename = os.path.join(example, "agents.py")
+        model_filename = os.path.join(example, "model.py")
+        readme_filename = os.path.join(example, "Readme.md")
+        app_filename = os.path.join(example, "app.py")
+
+        md_filename = f"{base_name}.md"
+        examples_md.append(base_name)
+
+        md_filepath = os.path.join(HERE, "examples", 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(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]),
+            )
+        )
+        fh.write(content)
+
+def setup(app):
+    setup_examples_pages()
+
+#
+if __name__ == "__main__":
+    setup_examples_pages()

docs/example_template.txt

@@ -0,0 +1,22 @@
+
+$readme_file
+
+## Agents
+
+```python
+$agent_file
+```
+
+
+## Model
+
+```python
+$model_file
+```
+
+
+## App
+
+```python
+$app_file
+```

docs/examples.md

@@ -0,0 +1,14 @@
+
+# Examples
+
+
+```{toctree}
+:maxdepth: 1
+
+boid flockers </examples/boid_flockers>
+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>
+
+```

docs/examples_overview_template.txt

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

docs/index.md

@@ -89,6 +89,7 @@ ABM features users have shared that you may want to use in your model
 Mesa Overview <overview>
 tutorials/intro_tutorial
 tutorials/visualization_tutorial
+Examples <examples>
 Migration guide <migration_guide>
 Best Practices <best-practices>
 How-to Guide <howto>

docs/overview.md

@@ -15,7 +15,8 @@ Mesa is modular, meaning that its modeling, analysis and visualization component
 
 Most models consist of one class to represent the model itself and one or more classes for agents. Mesa provides built-in functionality for managing agents and their interactions. These are implemented in Mesa's modeling modules:
 
-- `mesa.Model`, `mesa.Agent`
+- [mesa.model](apis/model)
+- [mesa.agent](apis/agent)
 - [mesa.space](apis/space)
 
 The skeleton of a model might look like this:

docs/packages.md

@@ -60,7 +60,7 @@ The commands above should also work with Anaconda, just replace the `pip` with `
 
 ## Package Development: A "How-to Guide"
 
-The purpose of this section is help you understand, setup, and distribute your Mesa package as quickly as possible. A Mesa package is just a Python package or repo. We just call it a Mesa package, because we are talking about a Python package in the context of Mesa. These instructions assume that you are a little familiar with development, but that you have little knowledge of the packaging process.
+The purpose of this section is to help you understand, setup, and distribute your Mesa package as quickly as possible. A Mesa package is just a Python package or repo. We just call it a Mesa package, because we are talking about a Python package in the context of Mesa. These instructions assume that you are a little familiar with development, but that you have little knowledge of the packaging process.
 
 There are two ways to share a package:
 
@@ -85,7 +85,7 @@ Most likely you created an ABM that has the code that you want to share in it, w
 >
 > 4. [Clone the repo to your computer](https://help.github.com/articles/cloning-a-repository/#platform-linux).
 >
-> 5. Copy your code directory into the repo that you cloned one your computer.
+> 5. Copy your code directory into the repo that you cloned on your computer.
 >
 > 6. Add a requirements.txt file, which lets people know which external Python packages are needed to run the code in your repo. To create a file, run: `pip freeze > requirements.txt`. Note, if you are running Anaconda, you will need to install pip first: `conda install pip`.
 >

mesa/examples/basic/conways_game_of_life/agents.py

@@ -12,10 +12,10 @@ def __init__(self, pos, model, init_state=DEAD):
         super().__init__(model)
         self.x, self.y = pos
         self.state = init_state
-        self._nextState = None
+        self._next_state = None
 
     @property
-    def isAlive(self):
+    def is_alive(self):
         return self.state == self.ALIVE
 
     @property
@@ -31,17 +31,17 @@ def determine_state(self):
         """
         # Get the neighbors and apply the rules on whether to be alive or dead
         # at the next tick.
-        live_neighbors = sum(neighbor.isAlive for neighbor in self.neighbors)
+        live_neighbors = sum(neighbor.is_alive for neighbor in self.neighbors)
 
         # Assume nextState is unchanged, unless changed below.
-        self._nextState = self.state
-        if self.isAlive:
+        self._next_state = self.state
+        if self.is_alive:
             if live_neighbors < 2 or live_neighbors > 3:
-                self._nextState = self.DEAD
+                self._next_state = self.DEAD
         else:
             if live_neighbors == 3:
-                self._nextState = self.ALIVE
+                self._next_state = self.ALIVE
 
     def assume_state(self):
         """Set the state to the new computed state -- computed in step()."""
-        self.state = self._nextState
+        self.state = self._next_state