Add a new tutorial for Models (#4790)

* Add tutorial for models

* updates

* Update docs/Project.toml

Co-authored-by: Navid C. Constantinou <[email protected]>

* Update docs/src/model_setup/overview.md

Co-authored-by: Navid C. Constantinou <[email protected]>

* Update docs/src/model_setup/overview.md

Co-authored-by: Navid C. Constantinou <[email protected]>

* add id

* tweaks + add link to QuickStart

* more links to other sections

* remove compats from Oceananigans deps and rely on Oceananigans compats

* add id

* incorporate IC in model/overview

* Restore examples and update documentation pages

Re-enable examples and organize documentation structure.

* Update make.jl

* Log execution of examples with process count

Add info log for executing examples with processes

* Uncomment model setup pages in make.jl

* Remove 'Setting initial conditions' from model setup

* Remove OceananigansXESMFExt from documentation build

* fix doctests

* fix doctests

* fix doctests

* reorder examples

* point to docstrings; don't reproduce them

* section title

---------

Co-authored-by: Navid C. Constantinou <[email protected]>
Co-authored-by: Simone Silvestri <[email protected]>

Author: 3 people

docs/Project.toml

@@ -7,7 +7,6 @@ DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
-Measures = "442fdcdd-2543-5da2-b0f3-8c86c306513e"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
 Polynomials = "f27b6e38-b328-58d1-80ce-0feddd5e7a45"
 Rotations = "6038ab10-8711-5258-84ad-4b1120ba62dc"
@@ -20,10 +19,5 @@ CUDA = "5.4 - 5.8.2"
 CairoMakie = "0.11, 0.12, 0.13, 0.14"
 Documenter = "1"
 DocumenterCitations = "1"
-JLD2 = "0.4, 0,5"
 Literate = "2.9"
-NCDatasets = "0.12.10, 0.13.1, 0.14"
 Polynomials = "4"
-Rotations = "1.0"
-SeawaterPolynomials = "0.3.9"
-StructArrays = "0.4, 0.5, 0.6, 0.7"

docs/make.jl

@@ -36,14 +36,14 @@ Distributed.addprocs(2)
     # docs built which extra workers is as efficient as possible.
     example_scripts = [
         "internal_tide.jl",
+        "langmuir_turbulence.jl",
         "shallow_water_Bickley_jet.jl",
+        "ocean_wind_mixing_and_convection.jl",
         "kelvin_helmholtz_instability.jl",
         "horizontal_convection.jl",
-        "langmuir_turbulence.jl",
         "baroclinic_adjustment.jl",
         "tilted_bottom_boundary_layer.jl",
         "convecting_plankton.jl",
-        "ocean_wind_mixing_and_convection.jl",
         "two_dimensional_turbulence.jl",
         "one_dimensional_diffusion.jl",
         "internal_wave.jl",
@@ -87,20 +87,13 @@ example_pages = [
 
 model_setup_pages = [
     "Overview" => "model_setup/overview.md",
-    "Setting initial conditions" => "model_setup/setting_initial_conditions.md",
-    "Architecture" => "model_setup/architecture.md",
-    "Number type" => "model_setup/number_type.md",
-    "Grid" => "model_setup/legacy_grids.md",
-    "Clock" => "model_setup/clock.md",
     "Coriolis (rotation)" => "model_setup/coriolis.md",
-    "Tracers" => "model_setup/tracers.md",
     "Buoyancy models and equation of state" => "model_setup/buoyancy_and_equation_of_state.md",
     "Boundary conditions" => "model_setup/boundary_conditions.md",
     "Forcing functions" => "model_setup/forcing_functions.md",
     "Background fields" => "model_setup/background_fields.md",
     "Turbulent diffusivity closures and LES models" => "model_setup/turbulent_diffusivity_closures_and_les_models.md",
     "Lagrangian particles" => "model_setup/lagrangian_particles.md",
-    "Diagnostics" => "model_setup/diagnostics.md",
     "Callbacks" => "model_setup/callbacks.md",
     "Output writers" => "model_setup/output_writers.md",
     "Checkpointing" => "model_setup/checkpointing.md",
@@ -158,7 +151,7 @@ pages = [
     # "Averages, integrals, and cumulative integrals" => "reductions_and_accumulations.md",
     # "Simulations" => simulations.md,
     # "FieldTimeSeries and post-processing" => field_time_series.md,
-    "Model setup (legacy)" => model_setup_pages,
+    "Models" => model_setup_pages,
     "Physics" => physics_pages,
     "Numerical implementation" => numerical_pages,
     "Simulation tips" => "simulation_tips.md",
@@ -180,13 +173,18 @@ format = Documenter.HTML(collapselevel = 1,
 
 DocMeta.setdocmeta!(Oceananigans, :DocTestSetup, :(using Oceananigans); recursive=true)
 
+OceananigansNCDatasetsExt = if isdefined(Base, :get_extension)
+    Base.get_extension(Oceananigans, :OceananigansNCDatasetsExt)
+else
+    Oceananigans.OceananigansNCDatasetsExt
+end
+
 makedocs(sitename = "Oceananigans.jl",
          authors = "Climate Modeling Alliance and contributors",
          format = format,
          pages = pages,
          plugins = [bib],
-         modules = [Oceananigans,
-                    isdefined(Base, :get_extension) ? Base.get_extension(Oceananigans, :OceananigansNCDatasetsExt) : Oceananigans.OceananigansNCDatasetsExt],
+         modules = [Oceananigans, OceananigansNCDatasetsExt],
          warnonly = [:cross_references],
          draft = false,        # set to true to speed things up
          doctest = true,       # set to false to speed things up

docs/src/grids.md

@@ -713,7 +713,7 @@ To obtain a discretization with a certain minimum spacing we need to play around
 and the number of cells.
 
 
-### Constant-to-stretched-spacing discretization
+### Reference-to-stretched-spacing discretization
 
 [`ReferenceToStretchedDiscretization`](@ref) returns a discretization with a constant reference spacing over
 some extent and beyond which the spacing increases with a prescribed stretching law; this allows a tighter

docs/src/model_setup/architecture.md

@@ -1,4 +1,4 @@
-# Forcing functions
+# [Forcing functions](@id forcing_functions)
 
 "Forcings" are user-defined terms appended to right-hand side of
 the momentum or tracer evolution equations. In `Oceananigans`, momentum