Docs reorganization (#2450)

* Create getting_started.md

* quick test

* Delete getting_started.md

* test hidden toc for examples

* remove packages.md

as suggested by @tpike3

* move examples and migration out of getting started

* some further refinement

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update getting_started.md

* Update index.md

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update best-practices.md

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update docs/getting_started.md

Co-authored-by: Ewout ter Hoeven <E.M.terHoeven@student.tudelft.nl>

* adds init of cell_space to docs

adds init of cell_space to docs

* fix typos in docs

* name changes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update getting_started.md

* Update conf.py

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Ewout ter Hoeven <E.M.terHoeven@student.tudelft.nl>

docs/apis/experimental.md

@@ -3,6 +3,11 @@ 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:
@@ -33,6 +38,11 @@ This namespace contains experimental features. These are under development, and
    :members:
 ```
 
+```{eval-rst}
+.. automodule:: experimental.cell_space.voronoi
+   :members:
+```
+
 ## Devs
 
 ```{eval-rst}

docs/apis/visualization.md

@@ -14,7 +14,7 @@ For a detailed tutorial, please refer to our [Visualization Tutorial](../tutoria
 ## User Parameters
 
 ```{eval-rst}
-.. automodule:: mesa.visualization.UserParam
+.. automodule:: mesa.visualization.user_param
    :members:
    :undoc-members:
    :show-inheritance:

docs/best-practices.md

@@ -24,7 +24,7 @@ All our [examples](examples) follow this layout.
 ## Randomization
 
 If your model involves some random choice, you can use the built-in `random`
-property that Mesa `Model` and `Agent` objects have. This works exactly
+property that many Mesa objects have, including `Model`, `Agent`, and `AgentSet`. This works exactly
 like the built-in `random` library.
 
 ```python
@@ -45,20 +45,24 @@ class AwesomeAgent(Agent):
     random_number = self.random.randint(0, 100)
 ```
 
-(The agent's random property is just a reference to its parent model's
-`random` property).
+`Agent.random` is just a convenient shorthand in the Agent class to `self.model.random`. If you create your own `AgentSet`
+instances, you have to pass `random` explicitly. Typically, you can simply do, in a Model instance,
+`my_agentset = AgentSet([], random=self.random)`. This ensures that `my_agentset` uses the same random
+number generator as the rest of the model.
+
 
 When a model object is created, its random property is automatically seeded
 with the current time. The seed determines the sequence of random numbers; if
 you instantiate a model with the same seed, you will get the same results.
 To allow you to set the seed, make sure your model has a `seed` argument in its
-constructor.
+`__init__`.
 
 ```python
 class AwesomeModel(Model):
 
   def __init__(self, seed=None):
-    pass
+    super().__init__(seed=seed)
+    ...
 
   def cool_method(self):
     interesting_number = self.random.random()

docs/conf.py

@@ -175,7 +175,9 @@
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    'migration_guide': [],  # No sidebar migration
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -338,7 +340,7 @@ def setup_examples_pages():
         app_filename = os.path.join(example, "app.py")
 
         md_filename = f"{base_name}.md"
-        examples_md.append(base_name)
+        examples_md.append((base_name, f"{kind}/{base_name}"))
 
         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)
@@ -354,7 +356,7 @@ def setup_examples_pages():
         content = template.substitute(
             dict(
                 readme=readme_md,
-            #     examples="\n".join([f"{' '.join(base_name.split('_'))} </examples/{base_name}>" for base_name in examples_md]),
+                example_paths="\n".join([f"{' '.join(a.split('_'))} </examples/{b}>" for a, b in examples_md]),
             )
         )
         fh.write(content)

docs/examples_overview_template.txt

@@ -1,3 +1,13 @@
 
 $readme
 
+
+
+```{toctree}
+:hidden: true
+:maxdepth: 2
+
+$example_paths
+
+
+```

docs/overview.md → docs/getting_started.md

@@ -1,9 +1,20 @@
-# Mesa Overview
+# Getting started
 Mesa is a modular framework for building, analyzing and visualizing agent-based models.
 
 **Agent-based models** are computer simulations involving multiple entities (the agents) acting and interacting with one another based on their programmed behavior. Agents can be used to represent living cells, animals, individual humans, even entire organizations or abstract entities. Sometimes, we may have an understanding of how the individual components of a system behave, and want to see what system-level behaviors and effects emerge from their interaction. Other times, we may have a good idea of how the system overall behaves, and want to figure out what individual behaviors explain it. Or we may want to see how to get agents to cooperate or compete most effectively. Or we may just want to build a cool toy with colorful little dots moving around.
 
-## Mesa Modules
+
+## Tutorials
+If you want to get a quick start on how to build agent based models with MESA, check the tutorials:
+
+- [Introductory Tutorial](tutorials/intro_tutorial): Learn how to create your first Mesa model.
+- [Visualization Tutorial](tutorials/visualization_tutorial.html): Learn how to create interactive visualizations for your models.
+
+## Examples
+Mesa ships with a collection of example models. These are classic ABMs, so if you are familiar with ABMs and want to get a quick sense of how MESA works, these examples are great place to start. You can find them [here](examples).
+
+
+## Overview of the MESA library
 
 Mesa is modular, meaning that its modeling, analysis and visualization components are kept separate but intended to work together. The modules are grouped into three categories:
 
@@ -165,10 +176,14 @@ results = mesa.batch_run(
 The results are returned as a list of dictionaries, which can be easily converted to a pandas DataFrame for further analysis.
 
 ### Visualization
-Mesa now uses a new browser-based visualization system called SolaraViz. This allows for interactive, customizable visualizations of your models. Here's a basic example of how to set up a visualization:
+Mesa now uses a new browser-based visualization system called SolaraViz. This allows for interactive, customizable visualizations of your models.
 
 > **Note:** SolaraViz is experimental and still in active development for Mesa 3.0. While we attempt to minimize them, there might be API breaking changes between Mesa 3.0 and 3.1. There won't be breaking changes between Mesa 3.0.x patch releases.
 
+The core functionality for building your own visualizations resides in the [`mesa.visualization`](apis/visualization) namespace
+
+Here's a basic example of how to set up a visualization:
+
 ```python
 from mesa.visualization import SolaraViz, make_space_component, make_plot_component
 
@@ -206,28 +221,42 @@ This will create an interactive visualization of your model, including:
 
 You can also create custom visualization components using Matplotlib. For more advanced usage and customization options, please refer to the [visualization tutorial](tutorials/visualization_tutorial).
 
-### Further resources
+## Further resources
 To further explore Mesa and its features, we have the following resources available:
 
-#### Tutorials
-- [Introductory Tutorial](tutorials/intro_tutorial): Learn how to create your first Mesa model.
-- [Visualization Tutorial](tutorials/visualization_tutorial.html): Learn how to create interactive visualizations for your models.
+### Best practices
+- [Mesa best practices](best-practices): an overview of tips and guidelines for using MESA.
 
-#### API documentation
+### API documentation
 - [Mesa API reference](apis): Detailed documentation of Mesa's classes and functions.
 
-#### Example models
+### Repository of models built using MESA
 - [Mesa Examples repository](https://github.com/projectmesa/mesa-examples): A collection of example models demonstrating various Mesa features and modeling techniques.
 
-#### Migration guide
+### Migration guide
 - [Mesa 3.0 Migration guide](migration_guide): If you're upgrading from an earlier version of Mesa, this guide will help you navigate the changes in Mesa 3.0.
 
-#### Source Ccode and development
+### Source Ccode and development
 - [Mesa GitHub repository](https://github.com/projectmesa/mesa): Access the full source code of Mesa, contribute to its development, or report issues.
 - [Mesa release notes](https://github.com/projectmesa/mesa/releases): View the detailed changelog of Mesa, including all past releases and their features.
 
-#### Community and support
+### Community and support
 - [Mesa GitHub Discussions](https://github.com/projectmesa/mesa/discussions): Join discussions, ask questions, and connect with other Mesa users.
 - [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org): Real-time chat for quick questions and community interaction.
 
 Enjoy modelling with Mesa, and feel free to reach out!
+
+
+
+
+
+```{toctree}
+:hidden: true
+:maxdepth: 7
+
+tutorials/intro_tutorial
+tutorials/visualization_tutorial
+Best Practices <best-practices>
+
+
+```

docs/index.md

@@ -50,9 +50,7 @@ pip install -U --pre mesa[rec]
 
 For help getting started with Mesa, check out these resources:
 
-- [Mesa Overview] - Learn about Mesa's core concepts and components
-- [Mesa Introductory Tutorial] - Build your first agent-based model
-- [Mesa Visualization Tutorial] - Learn how to create interactive visualizations with Solara
+- [Getting started] - Learn about Mesa's core concepts and components
 - [Migration Guide] - Upgrade to Mesa 3.0
 - [Mesa Examples] - Browse user-contributed models and implementations
 - [GitHub Discussions] - Ask questions and discuss Mesa
@@ -72,14 +70,11 @@ The original Mesa conference paper is [available here](http://conference.scipy.o
 :hidden: true
 :maxdepth: 7
 
-Mesa Overview <overview>
-tutorials/intro_tutorial
-tutorials/visualization_tutorial
+Getting started <getting_started>
 Examples <examples>
 Migration guide <migration_guide>
-Best Practices <best-practices>
 API Documentation <apis/api_main>
-Mesa Packages <packages>
+
 ```
 
 # Indices and tables
@@ -99,3 +94,5 @@ Mesa Packages <packages>
 [mesa introductory tutorial]: tutorials/intro_tutorial
 [mesa visualization tutorial]: tutorials/visualization_tutorial
 [migration guide]: migration_guide
+[Getting started]: getting_started
+