notebooks?

[francispoulin]

A few days ago I had suggested creating jupyter notebooks for all of the examples. Is there any interest in doing this?

If yes I think it would be easy enough to do and can suggest the following:

• could put it in a notebooks folder in examples,

• could modify the make.jl, I think, to generate these easily,

• might want to modify the docs to mention these and suggest them as an option.

If there is interest I can give it a go, but only if people agree this is a good idea. If not, one less thing for me to do ;)

[ali-ramadhan]

I think notebooks would be great to have! Also pretty related to recent discussion in #1149.

The examples use Literate.jl so we should be able to easily generate notebooks for all the examples by using Literate.notebook: https://fredrikekre.github.io/Literate.jl/v2/outputformats/

Right now we only generate Markdown files to put into the documentation: https://github.com/CliMA/Oceananigans.jl/blob/master/docs/make.jl#L48

I was thinking it might be useful to then put in a link to the generated notebooks at the top of each example so users can download the notebook if they wish (could also provide a clean script as an option). This would be pretty similar to what @navidcy and @glwagner have done for FourierFlows.jl examples I think (so they might have more thoughts on this) but there may be better or more visible ways of making the notebooks available to users.

[glwagner]

It'd be great to automatically generate notebooks from the existing scripts when the documentation builds!

[navidcy]

Yes. I’ve been meaning to do that but haven’t found time yet. I’ll draft a PR and we can continue chatting there.

[glwagner]

It's easy for users to generate notebooks from examples/ using Literate.notebook, it's something like

julia> using Literate

julia> Literate.notebook("two_dimensional_turbulence.jl")

What exactly do we need to resolve this issue? Do we want to generate notebooks and put them in the source code, to be hosted on github? Or do we want to include a note in the docs about how to generate notebooks from the Literate examples?

[francispoulin]

I thought we could generate the notebooks and have them hosted on github. That way the user can view them and know what they do before they download them. This would require a bit more compile time and storage but might be nice for some users.

[glwagner]

Do we need to execute the notebooks, or just generate the notebook code?

[glwagner]

It's expensive to build the docs now --- currently at around 90 minutes. Moving forward I think we hope to add more examples (as we have more features and capabilities to illustrate), so the costs will continue to increase. So I think it's likely we will only be able to afford to run examples once while we build the docs.

However, we can easily (I think) generate the notebook code (without executing the notebook) and host it on github. If we don't execute the notebook, we won't be able to view the output on github. People will have to look to the documentation to see output. Would that still be a satisfactory solution?

We can take inspiration from ClimaCore.jl:

https://github.com/CliMA/ClimaCore.jl/blob/main/docs/make.jl

for tutorial in TUTORIALS
    Literate.markdown(
        joinpath(@__DIR__, "tutorials", tutorial * ".jl"),
        joinpath(@__DIR__, "src", "tutorials");
        preprocess = preprocess_markdown,
    )
    Literate.notebook(
        joinpath(@__DIR__, "tutorials", tutorial * ".jl"),
        joinpath(@__DIR__, "src", "tutorials");
        execute = false,
    )
end

[glwagner]

Generating the notebook code is lightning fast and doesn't require compilation or storage of output so this has basically no cost (as far as I know) with execute=false.

[francispoulin]

I think generating the notebooks even without executing would be a nice addition. Since we run the scripts the notebooks should run as well.

[glwagner]

@francispoulin going to convert this to a discussion, so that users can find the info they need to convert examples to notebooks if they want to.