I’ll certainly look at the Convex.jl approach.
I hope it helps! I based my approach a bit off of TimeseriesPrediction.jl’s approach to examples, so that could be another package to look at.
From your description, the bundles are separate Github repos which can be “installed”, ready for Jupiter? That’s a cool idea.
For Convex.jl, I ended up just putting all the different examples (which are in separate literate files) together in one zip file after converting them to notebooks. So everything is in the Convex.jl git repo and there’s only one zip file. But with the Project.toml file and https://github.com/JuliaLang/IJulia.jl/pull/820, if one starts Jupyter from the directory of the unzipped folder, the environment should be right so you don’t have to add the dependencies (just instantiate). For more involved setups something similar could work for groups of examples.
On the .md files, doesn’t the Github pages branch contribute to the overall repo size? Clearly I need to study this more as it might also be applicable for another project where many (separate, different customers) cases have to be analyzed using FE methods!
Ah, probably it does. Repo size wasn’t really something I was thinking about for Convex.jl, just simplifying diffs from PRs (it’s easy to review PRs to literate files compared to PRs that change notebooks).
One solution could be to generate the notebooks and not execute them.
That’s what I’m doing now for Convex.jl. I’m still executing the code via Documenter in the markdown files (so the examples get rendered in the docs), but not executing it for the notebooks. I’d actually prefer to execute in the notebooks as well, since our files aren’t too big, and that way Travis will fail the docs build stage if the notebooks fail to execute. However, it already takes 20 minutes to build the docs on Travis due to executing all the examples when building the docs, so I didn’t want to push the build time up more by also executing the code in the notebooks. Anyway, docs build time is also something to think about if you’re considering putting the examples in the docs like we did with Convex.jl. It’s much slower on Travis than it is locally, I think partly since it needs to install and precompile all the packages each build.
One thing I thought was really cool about putting the examples in the docs is clicking the “edit on github” links on any of the examples take you to the literate file itself (thanks to a nice feature of Literate.jl). So if someone spots a typo or other change they want to propose, it all should be much easier to fix now (click edit, make the change in the github UI, send the PR with a nice plain text diff) versus before (fork the repo, boot up IJulia, open the notebook, make the change, PR with the notebook diff).