What is the proper way of running examples from a cloned package?
If I write some examples of the use of the package, and they are included when the package is cloned, how does the user conveniently run those examples? Or is there another (proper) way of including examples with your package?
Possible, but I suspect not quite the right thing to do. Obviously, some of the examples have been converted to tests already, but others print out information or write out files for postprocessing. They are really examples of how to use the toolkit. I suspect few people trawl the test files for examples of how to use the packages…
I do have an “examples” folder. The question is how does the user access these examples from the REPL?
It doesn’t seem particularly attractive to figure out where precisely the examples live and then to spell out the folder over and over again.
For a predecessor of the current package I used to have the examples in a separate repo. It seems that @ChrisRackauckas is saying that that is how he would do things. Any opinions from anyone else?
I was just giving examples of how people generally do things because there is no general framework. If you’re looking for some “project” as opposed to “package” workflow which runs examples that are not tests, it doesn’t exist (yet). Here are some previous discussions:
It would be easy to writeup a package which uses the examples folder in the Git repository to make something like:
# Run v0.x/MyProject/examples/Example1.jl with variable plot_solutions = true
Project.run("MyProject","Example1",plot_solutions = true)
# Run it in test mode: throws errors with `@test` fails
# Not part of CI, could take a long time or need extra resources
I was against this before, but I can see it being useful enough to call for inclusion into Base/Pkg3 sooner or later. That would give you what you want.
I don’t think that’s what you’re looking for, but FWIW, I used the folder-of-Jupyter-notebooks approach in ScikitLearn.jl and it works OK. I have a script that generates the index from the descriptions, and runtests.jl automatically runs the notebooks with NBInclude.jl.
Have a function in your package like run_example(name) = include(path_to_folder * name)?