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?
Put them in the test folder and Pkg.test("MyPackage").
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…
What are the alternatives?
I always look through the tests folder. There’s good stuff in there 
.
The alternative is to have a separate examples folder. Or have a separate repo with Jupyter notebooks (I wouldn’t put them in the same repo: they clog the Git history).
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
Project.test("MyProject","Example1") time!
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.
Thank you, @ChrisRackauckas . This will be useful to peruse to gain a feeling for what people think about examples and where they fit in with the packages.
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)?
Also, you can use dirname(@__FILE__) inside your run_example function to figure out where your package is currently installed, rather than trying to work out the path to each example manually.