Notes
Using Solvers and Other Additional Packages
Certain solvers may require a license or an additional installation. Since we want to test the tutorials using Travis CI and run them in the browser using Binder, we should always try to go for the solver which works out of the box with just a Package install. In case this is not possible, do not add the tutorial to the runtests.jl
file and add a line that it does not work with Binder. Note that this issue is not specific to solvers and may arise with other Julia packages as well.
Tangle
We use the tangle feature of Weave.jl to generate files for testing as it allows us extract code from a file. This enables us to skip cetains blocks of code we would not want for tests, such as:
Deliberate Errors
Tutorials might contain examples of what not to do and hence some code blocks can throw errors on purpose. These blocks cause tests to fail when we run the entire tutorial and hence they are skipped from tangle.
Installing Packages
Though code that installs packages will not cause tests to fail, it will slow them down. Since we are already adding all the required packages as dependencies, blocks that install packages are skipped from tangle.
Generating notebooks
The Weave.notebook
function converts the script to a notebook using nbconvert
and runs it using the project's IJulia.
The global IJulia's version not matching the project one can lead to cryptic errors.
Citations
Citations are added manually using links in markdown and not through tools like BibTeX. This method works for our use case as the number of citations per tutorial is quite less. Boilerplate code you can use is given below:
#' Lets add a citation[[1]](#c1).
#' Here's another one[[2]](#c2).
#' ### References
#' <a id='c1'></a>
#' 1. First citation in plain text.
#' <a id='c2'></a>
#' 2. Second citation in plain text.
Graphics in the Notebooks
The notebook
function in Weave.jl currently does not support Gadfly plot output(116). In case a tutorial has plots, you'll have to open the generated notebook in Jupyter and from the menu select "Cell > Run All".