Documentation for running the examples

[Armavica]

Hi, as part of the review that I am doing for JOSS (openjournals/joss-reviews#7723), I am trying to run the examples.

Even though I am relatively familiar with Rust and Cargo, it took me a little bit of time to understand how to run them. Have you considered adding some documentation (or READMEs) to explain the steps needed? Cloning the repository with submodules, moving to cellular_raza/cellular_raza-examples/cell_sorting (for example), running cargo run --bin default --release: this might be helpful for someone less familiar with git/Rust/Cargo.

Also, have you considered using Cargo's native support for examples? https://doc.rust-lang.org/cargo/reference/cargo-targets.html#examples

[jonaspleyer]

Even though I am relatively familiar with Rust and Cargo, it took me a little bit of time to understand how to run them. Have you considered adding some documentation (or READMEs) to explain the steps needed?

This seems like a very good addition to the project. I will work on adding more README.md files as I have already done within the other issue for the cell_sorting example.

Also, have you considered using Cargo's native support for examples? https://doc.rust-lang.org/cargo/reference/cargo-targets.html#examples

Most of the project is in line with general rust & cargo structure. But you are certainly right that adding examples explicitly would clear things up considerably.

Going further, it could be helpful to provide requirements.txt for the python plotting scripts.

• README.md files for examples
• explicit [[examples]] ... sections in Cargo.toml
• requirements.txt files for plotting scripts

[jonaspleyer]

That being said, I will probably still have some "old" examples lying around which I will keep in the main tree (not another repository) for (at least) the coming months to ensure any progress of the package conserves their functionality. However these examples might not be suited for end-users to directly follow and use. I will mention this in the README.md files which I will be adding.

[Armavica]

Sounds good! By the way, I should have mentioned it, but this is just a detail. The most important is that people can run your software, which is the case so far. What I am suggesting here is just what I think will make it easier for people to do so, but you may disagree on this point and leave out the [[example]]s if they would be difficult to add to your repository or if you think that the best way to run them is to follow the documentation of the showcases.

[jonaspleyer]

Thanks for clarifying that. I am happy to hear that. I will let you know how I decide. But overall it seems like a very good idea to me.

[jonaspleyer]

Concerning the [[example]] ... sections:
I came across this thread https://users.rust-lang.org/t/how-to-include-example-projects-in-workspaces/122375/4 which also suggests to simply include examples as individual packages when incorporating them inside a workspace.

To me, it is rather important to have individual Cargo.toml files for every example since they should be as much self-contained as possible. I have previously seen in other projects that this was not the case and would like to avoid that.

But I have added a README.md file listing all examples and how to run them. See https://github.com/jonaspleyer/cellular_raza/tree/master/cellular_raza-examples

[Armavica]

That's a very good point! I think that's great how it is now.

[jonaspleyer]

Closing this issue now.