Friendly "getting started" section that encompasses installation + running examples for new users?

[glwagner]

The installation instructions are helpful for users who have downloaded julia. However, to run examples one needs to know how to use git, and also to have a text editor. Neither of these is necessarily trivial so it might be nice both to provide some simple explanations about how to get started with running the examples, and also to link to info about text editing, IDEs, and using github.

[glwagner]

Maybe we can rename the section to "Getting started..."

[navidcy]

“Installation and Getting started”
or
“Installation and Get going...”
?

[ali-ramadhan]

I don't know if I would advocate for telling users to git clone the repository and study the Literate.jl examples in raw form for a few reasons:

1. git could be new to some beginners (and Windows users might not even have git installed) so this might be a high barrier to entry for some new users.
2. The Literate.jl examples in raw form mix Julia and Markdown, and have some extraneous stuff specific to building docs/examples like scattered nothing expressions. This may confuse some new users, especially if they're not familiar with Markdown.
3. I think cloning the repository should be done with the intention of working on or developing the package's source code.

What if we suggested they add/install the Plots.jl package (since it's used by all examples) and asked users to follow along with the examples, either by copy pasting into the REPL or by copy pasting into a script in a text editor that they then include in the Julia REPL. Would this be a lower entry barrier to "getting started"?

We should also point users to https://www.julia-vscode.org/ in case an IDE is more comfortable for them.

[glwagner]

How do you recommend running the examples without git clone? Copy pasting from github?

[christophernhill]

Is there anything useful in the approach here

https://youtu.be/GCj4xHUGZ0g?t=2555

their message was sort of that everything was really easy.
They used a Docker/Singularity container I think and it was a general presentation, but their example was Oceanigans.

[glwagner]

I guess git clone isn't necessary. But to get the code that runs examples, you have to download it from the internet somehow. This could involve clicking buttons or using git clone. Github certainly does let you download a repository by getting the zip file, and we can put a link that starts that download somewhere so that users don't have to use git clone. This would be the kind of thing that we might put in a set of expanded "getting started" section.

As for downloading the source or not, we currently put examples in the root directory, so ordinarily this would mean downloading, via mouse or git clone, a folder that includes the source code.

Should we move examples into a separate repo instead?

[glwagner]

2. The Literate.jl examples in raw form mix Julia and Markdown, and have some extraneous stuff specific to building docs/examples like scattered nothing expressions. This may confuse some new users, especially if they're not familiar with Markdown.

Where should users go to find examples?

If we think the examples are... bad examples... I think we should write new, better examples that we are proud to recommend to users.

[navidcy]

@ali-ramadhan does makes a fair point.

But there will be some learning curve either way... The user should either know some git, or they should be familiar with Julia's syntax, or Julia's project management (julia --project=...). To that extend, perhaps the doc instructions could suggest few avenues that the user can start running the examples. Cloning the repo could be one of them. But also copy-paste from the docs after ensuring the the proper Project.toml is instantiated could also be a viable option!

By the way Literate.jl provides ways to output the examples in different forms other than markdown for the docs.
https://fredrikekre.github.io/Literate.jl/v2/outputformats/
With some pre/postprocessing we can have Literate.jl strip out things like nothing #hide and then point the users to cleaner .jl scripts or Jupyter notebooks.

[navidcy]

Docker should be also mentioned as another avenue for users to be able to get examples running...

(@christophernhill)

[ali-ramadhan]

Yeah maybe making use of the different Literate.jl output formats could be nice. We could put a little banner at the top of each example, something like

Click here to download this example as a script, or click here to download this example as a Jupyter notebook.

?

[navidcy]

Yep. Somewhere in the top of the example in the documentation there should be these links...

This is a primitive form of what I was thinking: https://fourierflows.github.io/GeophysicalFlowsDocumentation/dev/generated/twodnavierstokes_decaying/

But, after this discussion I realised that we should be post-processing to strip the notebooks from nothing #hide and various things of that sort before Literate.jl makes a .ipynb file.

[glwagner]

I personally think that the most effective and productive way to use Oceananigans (eg, play around, experiment, run new simulations, plot new things) is to copy / paste an existing script that does something similar to what you would like to do and modify it.

So I think we need a solution that helps get users to this point as quickly and effortlessly as possible.

Julia environments and the ambiguity between the Oceananigans installed as a package in a specific environment, and the source code, is certainly a major source of confusion.

How about a link that downloads the examples and an environment (including Oceananigans, Plots and any other package needed to run the examples) in scripting-friendly format into a folder on the user's computer?

[glwagner]

We could possibly go the way of ClimateMachine and create a new folder called "tutorials" (code with extensive literate markup) and distinguish between these and "examples" (code that looks a lot more like a script we might write ourselves).

[ali-ramadhan]

I've seen that some other packages start their examples with something like

Install the required packages

   using Pkg
   pkg"add Oceananigans, Plots, JLD2"

Could we add these to the top of our examples? This should work no matter what the user is doing (minimizing user pain).

Most of the examples only need Oceananigans.jl, Plots.jl, and JLD2.jl/NCDatasets.jl.

[navidcy]

Not bad idea...
Just curious whether Literate will be installing Plots from scratch for every example.

[glwagner]

I think it may not after the first call...

(@v1.5) pkg> st
Status `~/.julia/environments/v1.5/Project.toml`
  [777c4786] ClimateMachine v0.3.0-DEV `https://github.com/CliMA/ClimateMachine.jl.git#master`
  [c27321d9] Glob v1.3.0
  [033835bb] JLD2 v0.2.4
  [ee78f7c6] Makie v0.11.1
  [9e8cae18] Oceananigans v0.44.0
  [91a5bcdd] Plots v1.6.12
  [438e738f] PyCall v1.92.1
  [d330b81b] PyPlot v2.9.0
  [295af30f] Revise v3.1.3

julia> using Pkg

julia> @time Pkg.add("JLD2")
  Resolving package versions...
No Changes to `~/.julia/environments/v1.5/Project.toml`
No Changes to `~/.julia/environments/v1.5/Manifest.toml`
  0.545965 seconds (2.62 M allocations: 218.625 MiB, 14.30% gc time)

[glwagner]

Could we add these to the top of our examples? This should work no matter what the user is doing (minimizing user pain).

I think that's a good idea. It fails after breaking API changes, but these typically don't persist long without a tag.

[navidcy]

OK, I'll do that on a separate PR for all examples.
Let's merge #1128 without it for now.

[glwagner]

How about this proposal: we create two new directories called tutorials and notebooks. We keep the source code in full Literate format in tutorials, and when the docs build, we use Literate's output formats to copy generated notebooks into notebooks/ and stripped down, non-markdown-polluted examples into examples/.

In the new Getting started section (or whatever we call it) we can include links to download either notebooks or examples, as well as directing users to the Documenter'd tutorials.

What do you think @ali-ramadhan @navidcy ?

[ali-ramadhan]

I think having three directories in the repo (tutorials, examples, notebooks) feels somewhat cumbersome.

Pretty sure we can get the same functionality you're proposing by generating the notebook and the stripped down example (both Literate.jl output) as part of the doc build (they would live the generated directory after the doc build), then we can link to them at the top of each example.

I guess this would be similar to what you guys do for FourierFlows.jl, e.g. https://fourierflows.github.io/GeophysicalFlowsDocumentation/dev/generated/twodnavierstokes_decaying/ (but we could just link to script + notebook instead of binder + nbviewer).

[glwagner]

I think that some people do clone the repo or click through github to look at files. This is the fastest way to see code. Our documentation may be amazing, but github is github and familiar to so many.

It was observed earlier in this issue that the scripts in examples/ are not actually good examples, since they have too much markup (they are really tutorials, rather than examples). I do think we want to provide bona fide examples somewhere in the source.

I think, if we don't want to put too many files in the source code, we should move tutorials somewhere else and keep the examples. The reason is that it means someone who only gets the source (doesn't look at online documentation) can get up and running quickly without having to go elsewhere.

[glwagner]

I guess to achieve what I'm suggesting, we'd move the current "examples" (which are tutorials) to docs/tutorials and then use Literate to generate the examples/ directory.

We can also provide a separate list of examples, but that's more work for us to maintain (and we'd have to start testing them again, since documentation builds would no longer test that they work).

[navidcy]

The wiki is a step towards this: https://github.com/CliMA/Oceananigans.jl/wiki

[glwagner]

Actually, I think we can close this because we decided that the wiki is the right place for stuff like this, while the docs should focus on documenting the source code.