Add documentation explaining scoping and work-arounds

[dlfivefifty]

I have a block of code like the following:

ret = 0
for k = 1:10
    ret += k
end
ret

Literate won't let me make a notebook unless I add global ret inside the for-loop. Even though the final Jupyter notebook is happy without the global ret.

Since this is the very first notebook in an introductory course I don't really want to talk about scoping, especially when I only need it to compile the file.

[fredrikekre]

This errors when you execute the notebook with Literate you mean? This is because Jupyter uses https://github.com/JuliaLang/SoftGlobalScope.jl so I guess Literate has to do the same for notebooks.

[dlfivefifty]

I don't understand: if I run the code in a Jupyter cell it works perfectly fine.

Is there a way to have Literate just create the notebook without running the cells? That is, so it will succeed even if the cells contain invalid code.

[fredrikekre]

I don't understand: if I run the code in a Jupyter cell it works perfectly fine.

Yes, because Jupyter (like the REPL) uses different scoping rules compared to regular Julia files. This is not the case when Literate runs the code.

Is there a way to have Literate just create the notebook without running the cells?

Yes, pass execute = false to Literate.notebook.