automated detection of updates to example files

Author: quaquel

docs/conf.py

@@ -296,20 +296,33 @@
 
 
 
+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 rst files for all examples
+    # create md files for all examples
     # check what examples exist
     examples_folder = osp.abspath(osp.join(HERE, "..", "examples"))
-
-    # fixme shift to walkdir
-    #  we should have a single rst page for each subdirectory
-
     basic_examples = [f.path for f in os.scandir(osp.join(examples_folder, "basic")) if f.is_dir() ]
     advanced_examples = []
     # advanced_examples = [f.path for f in os.scandir(osp.join(examples_folder, "advanced")) if f.is_dir()]
     examples = basic_examples + advanced_examples
 
-    # get all existing rst files
+    # get all existing md files
     md_files = glob.glob(os.path.join(HERE, "examples", "*.md"))
     md_files = {os.path.basename(os.path.normpath(entry)) for entry in md_files}
 
@@ -327,33 +340,23 @@ def setup_examples_pages():
         app_filename = os.path.join(example, "app.py")
 
         md_filename = f"{base_name}.md"
-        examples_md.append((base_name, f"./examples/{base_name}"))
-
-        # fixme should be replaced with something based on timestep
-        #  so if any(mymodelfiles) is newer then existing_md_filename
-        if md_filename not in md_files:
-            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(os.path.join(HERE, "examples", md_filename), "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)
-        else:
-            md_files.remove(md_filename)
-
-    # these md files are outdated because the example has been removed
-    for entry in md_files:
-        fn = os.path.join(HERE, "examples", entry)
-        os.remove(fn)
+        examples_md.append(base_name)
+
+        # let's establish the latest update to the example files
+        timestamps = [osp.getmtime(fh) for fh in [agent_filename, model_filename, readme_filename, app_filename]]
+        latest_edit = max(timestamps)
+
+        md_filepath = os.path.join(HERE, "examples", md_filename)
+
+        # if the example is new or the existing example md file is older than the latest update, create a new file
+        if md_filename not in md_files or latest_edit > osp.getmtime(md_filepath):
+            write_example_md_file(agent_filename, model_filename, readme_filename, app_filename, md_filepath, template)
+
+
+    # check if any md files should be removed because the example is removed
+    outdated_md_files = md_files - {f"{entry}.md" for entry in examples_md}
+    for entry in outdated_md_files:
+        os.remove(os.path.join(HERE, "examples", entry)  )
 
     # create overview of examples.md
     with open(os.path.join(HERE, "examples_overview_template.txt")) as fh:
@@ -362,7 +365,7 @@ def setup_examples_pages():
     with open(os.path.join(HERE, "examples.md"), "w") as fh:
         content = template.substitute(
             dict(
-                examples="\n".join([f"{' '.join(base_name.split('_'))} <{file_path[2::]}>" for base_name, file_path in examples_md]),
+                examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/<base_name>>" for base_name in examples_md]),
             )
         )
         fh.write(content)

docs/examples.md

@@ -5,10 +5,10 @@
 ```{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>
+boid flockers </examples/<base_name>>
+virus on network </examples/<base_name>>
+conways game of life </examples/<base_name>>
+schelling </examples/<base_name>>
+boltzmann wealth model </examples/<base_name>>
 
 ```

docs/examples/conways_game_of_life.md

@@ -53,10 +53,10 @@ class Cell(Agent):
         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
@@ -72,20 +72,20 @@ class Cell(Agent):
         """
         # 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
 
 ```
 

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