Improving the examples

[rht]

We have proposed several ways to improve the examples UX:

• Discuss: Moving examples to examples repo #963, Move Mesa examples to another repo with sub classing to this repo?  #134 are about moving the examples to a separate repo. This is needed so that we can have more users submitting examples. E.g. the El Farol example (Add El Farol Problem in mesa framework under example folder #1057) has a fat dependency and would bog down the CI if merged to current main repo
• Easier way to run Mesa examples #1228 easier way to run examples
• docs: Improve examples install instructions #1274 improve examples install instructions. This is because the issue Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt' #315 is among the top most visited page. This means that people have problem installing the examples

To combine all the solutions above, I think we can the examples split into:

1. core examples that are still part of the core Mesa CI, that are additionally easily importable and runnable.
2. more complex examples, examples with complex dependencies, etc, should live in the separate examples repo. This applies to El Farol and arguably Sugarscape with trading.

Regarding with easier way to run the examples, however, there are several ways to do it:

1. Implement Easier way to run Mesa examples #1228 -- this also serves as a quick starting point if people want to inherit and modify the example classes without much boilerplate
2. Implement the CLI command mesa initialize_examples (as proposed in docs: Improve examples install instructions #1274 (comment)) that will create a folder "mesa_examples" that contains all the core examples. And we will have to modify the readme in the core examples to use this command instead.
3. Implement both of point 1 and 2
4. Do nothing and just stick to Git. See e.g. Pytorch examples https://github.com/pytorch/examples. However, @Corvince had raised a concern about requiring git clone to prepare the examples makes it harder for people.

Cast your vote for the last 4 options!

[wang-boyu]

At the moment I would vote for both 1 and 2, but a slightly different version of 2. Instead of splitting examples into core and separated repo, I would suggest to keep all examples together within Mesa to avoid confusions.

Regarding 2, for simple examples we can simply re-use mesa runserver examples/wolf_sheep. For complex examples, perhaps we could update the runserver command to let it install example-specific dependencies before running the example. But this would introduce some difficulties to our example test cases.

In the future if the examples folder grows too large (e.g., over 100 examples in various application areas), then we can move them all into a separate repo. (Or would you prefer to do it now?)

Besides, I think it would be great to document how to contribute examples to encourage the community.

[rht]

In the future if the examples folder grows too large (e.g., over 100 examples in various application areas), then we can move them all into a separate repo.

It is likely that the current examples size is small because we are gating which examples can be put in.

Besides, I think it would be great to document how to contribute examples to encourage the community.

Also, the problem with merging lots of examples is that it becomes the responsibility of Mesa devs to maintain these examples. Too centralized. Imagine doing this for 100+ examples. We'd want a meta repo (in the style of "awesome x") that contains links to other repos, e.g. https://github.com/ncsa/COVID19-mesa. In this context, I'd consider putting separate repos under 1 organization, like projectmesadata, also has centralization problem.

[jackiekazil]

It is likely that the current examples size is small because we are gating which examples can be put in.
I think this is truly. Traditionally examples have been used to illustrate features, but maybe we need to consider examples in two different ways -- 1) Examples that illustrate features 2) Examples in general
Maybe we add a pointer in doc strings to an example that illustrates a feature in action, so that if someone wants to see how it is implemented, they can easily do this.

RE: Lots of examples
Maybe we have two sets? I think it would be beneficial to create a place that is a hub of examples and different takes on examples.

For the record -- I like 3 (which is 1 & 2). But maybe we still put examples in a separate repo and the initialization is the cloning of the repo? So if someone wants to contribute back to the examples -- it is easier & clearer.