Move use cases to docs folder.

[ismael-lajaaiti]

Currently use cases featured in the draft of the EcologicalNetworksDynamics paper are stored in the use_cases/ folder. However this is not very convenient for users to access them (as they have to clone the git repository to do so). The best would be to include them directly in the documentation. But, some of the use cases take a long time to run which make it hard/impossible to re-run them each time we want to generate the documentation.

Then, the solution would be to add an option to docs/make.jl to choose whether or not we run the use cases (e.g. --fast vs. --full).

Note: I am not sure GitHub will like that we run long simulations each time we want to deploy the doc...

[iago-lito]

Agreed. I believe this would be a good improvement to the docs, boiling down to "Adding a 'Use cases' section" to the doc's Home Page.

However, this improvement is non-trivial because uses cases take a long time to run and they generate various non-source binary artifacts (.jldata, .png, .pdf..) required to produce the final output IIUC. I have a strong opinion that these artifacts must not be checked-in like regular .jl or .md source files, because they would bloat the repo with unnecessary, heavy commits as the project evolves, linger on in the archives with all their meaningless updated copies forever, and consume unnecessary disk space / internet bandwidth on every machine / network that EcologicalNetworksDynamics.jl users and developers would use in the future.

In this respect, I would prefer the following questions to be addressed first:

• How to make it possible to construct a "fast" version of the docs locally?
  • docs/make.jl could be refined to accept either --fast or --full arguments.
• Will the tests run the use cases code then?
  • If yes: how to opt-out of that?
  • If no: how to opt-in?
• What are the limits of github's CI service? Would 2/3 hours multithreaded julia simulations, required to generate the docs and figures, fit within our free plan?
  • If yes, how to limit the execution of these use-cases scripts to not-every-single-push to PRs, but to major updates of the package only?
  • If no, where to run the scripts ? And where to host the artifacts ?
    • Running them at the lab is an option.
    • Hosting them at the lab (or any institutional service we can access) is an option.
    • Hosting them as "github releases" artifacts is an option.
    • Hosting the "Uses cases" section as a separate website is an option.

I must say that hosting calculations and data to maintain an up-to-date documentation website is not something I'm exactly familiar with. We will need to learn more about common practices in this respect, the exact stakes and the pitfalls to avoid.