docs: Improve examples install instructions

[rht]

If you look at https://github.com/projectmesa/mesa/graphs/traffic, #315 is the 3rd most visited page. This means that the readme of the examples are not clear enough to indicate that they must be in the directory containing the requirements.txt.

[rht]

#1275 is a good example on how to clarify the readme. Help wanted for the rest of the examples!

[Corvince]

I don't think #1275 is a good way to solve this problem. I'll explain myself later (probably tomorrow) but please don't change the other examples before having a discussion

[tpike3]

@Corvince intriguing, I look forward to seeing what you are thinking.

[Corvince]

Yes, sorry for not stating my concerns directly, but I was on the move and just saw that recently there have been a lot of contributions to mesa, which is great, but I feared someone would start working on this directly. And I also wanted to commit myself ;)

Anyways, I have 2 main concerns with instructing people to use git to clone the repository:

1. git is not always available. If people trip over pip install -r requirements (which I think I also did using mesa for the first time), they are probably rather inexperienced. People without a git installation (i.e. primarly windows users) will probably trip over a failing git clone as well.
2. If people manage to clone the repository, they now have a local, but uninstalled copy of mesa. Chances are they will try to modify mesa code and wonder why it doesn't work, not realizing this is not the mesa code they use when doing import mesa.

I am not sure what the best intermediant solution is, but the cleanest solution I always had on top of my mind was to create a mesa download_examples command that downloads and extracts a zip of the matching examples. But we would need to provide that versioned zip. We could automate this with each release and for example use Github Pages, so we have a link like https://projectmesa.github.io/examples/v0.9.0/examples.zip. Versioning is also important because currently the examples might be out of sync with the latest or certainly older mesa releases and even if people manage to clone them might not be able to run them.

[rht]

That is a valid concern.

Chances are they will try to modify mesa code

I don't think this is common. Most people will modify the examples code instead.

#1275 may not be a comprehensive solution to the problem, but at least it makes the steps explicit, instead of assuming that people have already cloned the Git repo. People will see the git clone command and look up on the internet on how to set up Git. They no longer assume: "oh, pip install mesa is sufficient!".

If you notice, 2 of the comments in #315 stated the git clone or properly cd-ing to the Git repo:

• Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt' #315 (comment)
• Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt' #315 (comment)

As with improving the UX of running the examples starting with 0 knowledge in Python (IMO, this is a superset of the problem of this issue), this will take time to design. And so #1275 is a viable solution for now. In addition to mesa download_examples, another viable solution is to implement the Jupyter GUI interface (#1263) so that people can execute the examples on Colab with 0 installation.

[rht]

#1228 is another option.

[Corvince]

#1275 may not be a comprehensive solution to the problem, but at least it makes the steps explicit, instead of assuming that people have already cloned the Git repo. People will see the git clone command and look up on the internet on how to set up Git. They no longer assume: "oh, pip install mesa is sufficient!".

Hmm I think we are getting somewhere, where we make too many assumptions on what people might or might not think. But I don't follow the argument why people would think pip install mesa is sufficient when it fails to install the requirements vs when git is not installed.

But I totally agree that #1275 is an intermediant solution. In that case however I would prefer to also state the pitfalls explicitly.

It is also not surprising that people mention git cloning, since this is currently required. Doesn't mean its a good solution. Case in point: If you clone the repo right now and try to run the sugarscape_cg model it will fail with the latest release version (mesa 0.9.0).

Another example for executing an example is deploying it on Heroku: PR and example: https://mesa-schelling-example.herokuapp.com/

#1228 has the same discussion point as #568, namely whether the examples should be a part of mesa or inside their own repo (#134)

[rht]

But I don't follow the argument why people would think pip install mesa is sufficient when it fails to install the requirements vs when git is not installed.

Here are some data points:

• "However, I immediately ran into a problem, after using pip install mesa, I tried to install the requirements (pip install -r requirements.txt) in the terminal." Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt' #315 (comment)
• Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt' #315 (comment)

If you clone the repo right now and try to run the sugarscape_cg model it will fail with the latest release version (mesa 0.9.0).

This is a bug that needs to be addressed on its own. I don't recall any breaking changes between latest main and latest release (0.9.0), so something must have slipped through.

I'd say the scope of this issue (#1274) should be limited to improving/clarifying the examples install instruction, and not more.

We should discuss the general strategy on making it easy to run examples via Heroku demo, import mesa.examples #1228 / $ mesa examples #568, mesa download_examples, Jupyter GUI #1263, and so in, in a separate space.

[Corvince]

If you clone the repo right now and try to run the sugarscape_cg model it will fail with the latest release version (mesa 0.9.0).

This is a bug that needs to be addressed on its own. I don't recall any breaking changes between latest main and latest release (0.9.0), so something must have slipped through.

Don't worry you don't need to recall anything here. This was just an example. I also wouldn't consider it a bug, the state of mesa and the examples on the repo is consistent in itself. This is a general problem with the current structure. Try to install any older version of mesa and run the examples, a lot of them probably won't work.

Just to be clear, I agree that #1275 is an immediate solution to this problem. And if someone has the time and energy to apply it to all examples feel free to do so - but it will be a change that should be reverted some time in the future when we have a better running-the-examples strategy. I am just not sure if it is worth the effort. (And I bet someone will eventually ask why the git clone command fails)

[rht]

Try to install any older version of mesa and run the examples, a lot of them probably won't work.

OK, this can be mitigated by doing mesa>=<last major version> in the requirements.txt of the example, and by explicitly stating in the readme that the user must run the pip install -r requirements.txt when they want to run the example for the first time.

I see #1275 as a complementary solution to mesa examples / mesa ... for people who prefer to see the source code from a git clone, and so, should stay. Some people may find the mesa ... interface to be opaque. Again, explicit instruction is the key here.

[Corvince]

OK, this can be mitigated by doing mesa>=<last major version> in the requirements.txt of the example, and by explicitly stating in the readme that the user must run the pip install -r requirements.txt when they want to run the example for the first time.

But this is the other way around. This forces the mesa version to match the example. The usual need is to find examples matching the used version. Also, this obviously doesn't work for unreleased versions of mesa, i.e. changes in the main branch.

I see #1275 as a complementary solution to mesa examples / mesa ... for people who prefer to see the source code from a git clone, and so, should stay. Some people may find the mesa ... interface to be opaque. Again, explicit instruction is the key here.

It depends on what solution we will come up with, but mesa download_examples would of course download the examples source code, I don't understand what is opaque about that?

[rht]

But this is the other way around. This forces the mesa version to match the example. The usual need is to find examples matching the used version. Also, this obviously doesn't work for unreleased versions of mesa, i.e. changes in the main branch.

If you want examples that work on mesa==<old release>, you can do git checkout <old release>.

It depends on what solution we will come up with, but mesa download_examples would of course download the examples source code, I don't understand what is opaque about that?

Because some people (not all) prefer to see the source code, the exact commit hash, and the past revisions from Git. It's more transparent.