Can we build examples separately from makedocs?

[glwagner]

Our suite of examples is fairly expensive; in recent runs the documentation build exceeds 90 minutes.

If we're able to "build" the examples first, before calling makedocs:

Oceananigans.jl/docs/make.jl

Lines 155 to 165 in 8da72d1

	makedocs(bib,
	sitename = "Oceananigans.jl",
	authors = "Ali Ramadhan, Gregory Wagner, John Marshall, Jean-Michel Campin, Chris Hill",
	format = format,
	pages = pages,
	modules = [Oceananigans],
	doctest = true,
	strict = true,
	clean = true,
	checkdocs = :none # Should fix our docstring so we can use checkdocs=:exports with strict=true.
	)

we can probably speed up the build. This is crucial now because we need to add new examples both for HydrostaticFreeSurfaceModel and for simulations in complex domains via ImmersedBoundaryGrid. We can also move some examples to the GPU and either speed them up, run them at higher resolution, or both.

What I know now: we provide .md files to makedocs, which then expands code blocks and generates .html:

Oceananigans.jl/docs/make.jl

Line 66 in 8da72d1

"Eady turbulence" => "generated/eady_turbulence.md",

Oceananigans.jl/docs/make.jl

Line 133 in 8da72d1

"Examples" => example_pages,

Oceananigans.jl/docs/make.jl

Line 159 in 8da72d1

pages = pages,

I think one solution is to generate the .html (by running code, which generates images and animations + links in the html) in separate buildkite jobs, and then somehow generate links to the pre-built .html in the "primary" make.jlcall to makedocs before deploydocs.

[iuryt]

I don't know this fits here, but I was thinking about a way to have a separate repository for examples from community that doesn't affect the test running time of the main repo.

The repo could generate a wiki-like page with the examples. We could give a code template for the simulations. For instance, all simulations must inform and check the version of Oceananigans and it's dependencies. Or maybe containing a yml equivalent for Julia project. What do you guys think?

I know this can get messy.. but it could be a nice way to avoid people reinventing the wheel while making their own simulations. With enough time, almost any experiment will have some others similar.

[glwagner]

I think we'll want a "community repo" for cases eventually.

Something like https://github.com/FluxML/model-zoo if I understand the purpose of that correctly.

For instance, all simulations must inform and check the version of Oceananigans and it's dependencies. Or maybe containing a yml equivalent for Julia project.

Isn't an ordinary Julia environment enough? For the community repo I think either

1. There is one repo-wide Project.toml and all examples are kept up to date or
2. Each example has it's own Project.toml.

As I understand the flux model zoo takes approach 1 (this is in principle better, because otherwise the examples grow stale and cease to be useful). However, that requires maintenance and substantial effort.

I think we will still want in-house examples in addition to an external community repo.

[glwagner]

Duplicate of #1053