Oceananigans.jl: README example is excessively large + README needs updating for current julia REPL look

[glwagner]

The README example builds a grid of size (100, 100, 50), which is non-small. We should make the intro example more bite-size.

[navidcy]

my 2 cents: It's a bit "tricky" to have code in the README since with constant code upgrades oftentimes the README code gets outdated...

[glwagner]

my 2 cents: It's a bit "tricky" to have code in the README since with constant code upgrades oftentimes the README code gets outdated...

That's true, probably best not to have too much. I personally find code in the README to be super helpful for "quick starting" though...

[navidcy]

Actually me too!
(unless it's broken)

[glwagner]

Actually, it probably wouldn't be that hard to run code in the README in a test. Somebody should write a package for that.

[ali-ramadhan]

Could do something like

using Markdown
readme = Markdown.parse(read("README.md", String))
julia_code_snippets = filter(c -> c isa Markdown.Code && c.language == "julia", readme.content)
for code_snippet in julia_code_snippets
    # Need begin and end in case code snippet is multi-line.
    Meta.parse("begin $(code_snippet.code) end") |> eval
end

but then the code blocks under "Installation instructions" should not be julia code blocks.

[glwagner]

but then the code blocks under "Installation instructions" should not be julia code blocks.

That's ok for me... we really want "julia-repl" highlighting for those blocks anyways.

Or, we can further-filter the lines that start with julia> ?

[glwagner]

It doesn't actually help to ask for julia syntax highlighting in the installation instructions anyways:

[glwagner]

What it looks like for me:

In fact, a screenshot rather than code could make more sense ? (Note that its also out of date with how the current julia REPL / package manager looks)

[glwagner]

Actually wondering if we should provide code that installs julia:

using Pkg
Pkg.add("Oceananigans")
Pkg.instantiate()

Then people can copy paste like they really want to.

If they know how to use the package manager, they already know what to do (or we can add a separate comment for such people).

[ali-ramadhan]

Hmmm, yeah copy-pastable code for installation might be better. Would rather use package mode but the benefit of being to copy paste is pretty sweet.

[glwagner]

We could use something like

Julia's package manager will happily install the latest version of Oceananigans for you:

using Pkg
Pkg.add("Oceananigans")
Pkg.instantiate()

Alternatively, you can press ] from Julia's REPL to enter package manager mode and type pkg> add Oceananigans followed by pkg> instantiate. We recommend installing Oceananigans with the built-in Julia package manager, because this installs a stable, tagged release.

[glwagner]

Another README issue: we should change

It is designed to solve the rotating Boussinesq equations...

to

It solves the rotating Boussinesq equations...