remove how-to guide and update docs in places (#2449)

Author: quaquel

docs/howto.md

@@ -78,7 +78,6 @@ tutorials/visualization_tutorial
 Examples <examples>
 Migration guide <migration_guide>
 Best Practices <best-practices>
-How-to Guide <howto>
 API Documentation <apis/api_main>
 Mesa Packages <packages>
 ```

docs/index.md

@@ -259,7 +259,7 @@
     "\n",
     "With the basics of the Agent class and Model class created we can no activate the agents to `do` things\n",
     "\n",
-    "**Background:** Mesa's `do` function calls agent functions the grow your ABM. A step is the smallest unit of time in the model, and is often referred to as a tick. The `do` function and Python functionality can be configured to activate agents in different orders. This can be important as the order in which agents are activated can impact the results of the model [Comer2014]. At each step of the model, one or more of the agents -- usually all of them -- are activated and take their own step, changing internally and/or interacting with one another or the environment. A overview of different ways to employ the `do` function for different activation regimes can be found in the [\"How To\" Guide](https://mesa.readthedocs.io/latest/howto.html).\n",
+    "**Background:** Mesa's `do` function calls agent functions the grow your ABM. A step is the smallest unit of time in the model, and is often referred to as a tick. The `do` function and Python functionality can be configured to activate agents in different orders. This can be important as the order in which agents are activated can impact the results of the model [Comer2014]. At each step of the model, one or more of the agents -- usually all of them -- are activated and take their own step, changing internally and/or interacting with one another or the environment.\n",
     "\n",
     "**Model-specific information:** For this section we will randomly reorder the Agent activation order using  `mesa.Agent.shuffle_do` and have the agents `step` function print the agent unique id they are assigned during the agent creation process. \n",
     "\n",
@@ -1498,9 +1498,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "**note for Windows OS users:** If you are running this tutorial in Jupyter, make sure that you set `number_processes = 1` (single process). If `number_processes` is greater than 1, it is less straightforward to set up. You can read [Mesa's how-to guide](https://github.com/projectmesa/mesa/blob/main/docs/howto.md), in 'Using multi-process `batch_run` on Windows' section for how to do it."
-   ]
+   "source": "**note for Windows OS users:** If you are running this tutorial in Jupyter, make sure that you set `number_processes = 1` (single process). If `number_processes` is greater than 1, it is less straightforward to set up. For details on how to use multiprocessing on windows, see [multiprocessing's programming guidelines](https://docs.python.org/3/library/multiprocessing.html#multiprocessing-programming). "
   },
   {
    "cell_type": "code",

docs/tutorials/intro_tutorial.ipynb

@@ -1,4 +1,29 @@
-"""batchrunner for running a factorial experiment design over a model."""
+"""batchrunner for running a factorial experiment design over a model.
+
+To take advantage of parallel execution of experiments, `batch_run` uses
+multiprocessing if ``number_processes`` is larger than 1. It is strongly advised
+to only run in parallel using a normal python file (so don't try to do it in a
+jupyter notebook). Moreover, best practice when using multiprocessing is to
+put the code inside an ``if __name__ == '__main__':`` code black as shown below::
+
+    from mesa.batchrunner import batch_run
+
+    params = {"width": 10, "height": 10, "N": range(10, 500, 10)}
+
+    if __name__ == '__main__':
+        results = batch_run(
+            MoneyModel,
+            parameters=params,
+            iterations=5,
+            max_steps=100,
+            number_processes=None,
+            data_collection_period=1,
+            display_progress=True,
+        )
+
+
+
+"""
 
 import itertools
 import multiprocessing