Merge pull request projectmesa#1072 from projectmesa/oct_2021_doc_update

Tweaking and improving the documentation

docs/apis/api_main.rst

@@ -5,8 +5,8 @@ APIs
    :maxdepth: 3
 
    Base Classes <init>
-   batchrunner
-   datacollection
-   space
    time
+   space
+   datacollection
+   batchrunner
    visualization

docs/apis/batchrunner.rst

@@ -1,5 +1,2 @@
-Batchrunner
------------
-
 .. automodule:: batchrunner
    :members:

docs/apis/datacollection.rst

@@ -1,5 +1,2 @@
-Data Collection
----------------
-
 .. automodule:: datacollection
    :members:

docs/apis/init.rst

@@ -1,5 +1,8 @@
-init
+Base Classes
 ----
 
-.. automodule:: __init__
+.. autoclass:: mesa.Agent
    :members:
+
+.. autoclass:: mesa.Model
+   :members:

docs/apis/space.rst

@@ -1,5 +1,3 @@
-Space
------------
-
 .. automodule:: mesa.space
    :members:
+   :inherited-members:

docs/apis/time.rst

@@ -1,2 +1,3 @@
 .. automodule:: mesa.time
    :members:
+   :inherited-members:

docs/conf.py

@@ -58,7 +58,7 @@
 
 # General information about the project.
 project = "Mesa"
-copyright = "2016, Project Mesa Team"
+copyright = "2015-2021, Project Mesa Team"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -92,7 +92,13 @@
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-# add_module_names = True
+add_module_names = False
+
+# Sort members by the order in the source files instead of alphabetically
+autodoc_member_order = 'bysource'
+
+# Show both the class-level docstring and the constructor docstring
+autoclass_content = 'both'
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.

docs/index.rst

@@ -12,13 +12,13 @@ Mesa: Agent-based modeling in Python 3+
 It allows users to quickly create agent-based models using built-in core components (such as spatial grids and agent schedulers) or customized implementations; visualize them using a browser-based interface; and analyze their results using Python's data analysis tools. Its goal is to be the Python 3-based counterpart to NetLogo, Repast, or MASON.
 
 
-.. image:: https://cloud.githubusercontent.com/assets/166734/8611697/ce61ad08-268a-11e5-880b-4776dd738e0e.png
+.. image:: https://raw.githubusercontent.com/projectmesa/mesa/main/docs/images/Mesa_Screenshot.png
    :width: 100%
    :scale: 100%
    :alt: A screenshot of the Schelling Model in Mesa
 
 *Above: A Mesa implementation of the Schelling segregation model,
-being visualized in a browser window and analyzed in an IPython
+being visualized in a browser window and analyzed in a Jupyter
 notebook.*
 
 .. _`Mesa` : https://github.com/projectmesa/mesa/
@@ -71,7 +71,6 @@ If you would like to add a feature, please reach out via `ticket`_ or the `email
 * `Github`_
 
 .. _`ticket` : https://github.com/projectmesa/mesa/issues
-.. _`email list` : https://groups.google.com/d/forum/projectmesa
 .. _`Contributors guide` : https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.rst
 .. _`Github` : https://github.com/projectmesa/mesa/
 

mesa/agent.py

@@ -13,7 +13,12 @@ class Agent:
     """Base class for a model agent."""
 
     def __init__(self, unique_id: int, model: Model) -> None:
-        """Create a new agent."""
+        """Create a new agent.
+
+        Args:
+            unique_id (int): A unique numeric identified for the agent
+            model: (Model): Instance of the model that contains the agent
+        """
         self.unique_id = unique_id
         self.model = model
         self.pos = None

mesa/datacollection.py

@@ -240,8 +240,7 @@ def get_agent_vars_dataframe(self):
         rep_names = [rep_name for rep_name in self.agent_reporters]
 
         df = pd.DataFrame.from_records(
-            data=all_records,
-            columns=["Step", "AgentID"] + rep_names,
+            data=all_records, columns=["Step", "AgentID"] + rep_names,
         )
         df = df.set_index(["Step", "AgentID"])
         return df

mesa/space.py

@@ -66,28 +66,6 @@ class Grid:
         width, height: The grid's width and height.
         torus: Boolean which determines whether to treat the grid as a torus.
         grid: Internal list-of-lists which holds the grid cells themselves.
-
-    Methods:
-        get_neighbors: Returns the objects surrounding a given cell.
-        get_neighborhood: Returns the cells surrounding a given cell.
-        get_cell_list_contents: Returns the contents of a list of cells
-            ((x,y) tuples)
-        neighbor_iter: Iterates over position neighbours.
-        coord_iter: Returns coordinates as well as cell contents.
-        place_agent: Positions an agent on the grid, and set its pos variable.
-        move_agent: Moves an agent from its current position to a new position.
-        iter_neighborhood: Returns an iterator over cell coordinates that are
-        in the neighborhood of a certain point.
-        torus_adj: Converts coordinate, handles torus looping.
-        out_of_bounds: Determines whether position is off the grid, returns
-        the out of bounds coordinate.
-        iter_cell_list_contents: Returns an iterator of the contents of the
-        cells identified in cell_list.
-        get_cell_list_contents: Returns a list of the contents of the cells
-        identified in cell_list.
-        remove_agent: Removes an agent from the grid.
-        is_cell_empty: Returns a bool of the contents of a cell.
-
     """
 
     def __init__(self, width: int, height: int, torus: bool) -> None:
@@ -138,9 +116,7 @@ def __getitem__(self, index: Sequence[Coordinate]) -> List[GridContent]:
     def __getitem__(
         self,
         index: Union[
-            int,
-            Sequence[Coordinate],
-            Tuple[Union[int, slice], Union[int, slice]],
+            int, Sequence[Coordinate], Tuple[Union[int, slice], Union[int, slice]],
         ],
     ) -> Union[GridContent, List[GridContent]]:
         """Access contents from the grid."""