Update Spaces documentation page

[charleskawczynski]

We should probably improve the user-side documentation of making grids / spaces, as a sort of introduction to using basic ClimaCore components.

[charleskawczynski]

From #2082 (review):

As a new user

As a new user visiting this repo to learn more about how to set up a simulation, I click on "Docs". Nowhere on the left bar there's a mention of the computational domain. So, I click on "Examples". Nowhere in the page there's a mention about the computation domain. I am lost.

As a user with familiarity with the concept of Space but not the details

The only trace that convenience constructors for Spaces exist is a brief mention to News item. They are never used in any example. The docstring just mentions that they call some Grid constructor, but, having little familiarity with the internals, I don't know what Grids are and why I should care about them. The examples in the docstrings are trivial and don't tell me much. I have to dig to the test cases to find a place where I can learn more about these functions, but even there, the tests are just checking properties of the underlying Grid.

As scientist developing ClimaAtmos

I want to set up use these constructors to set up a Space. I read the docstring to learn about this feature. I've never really heard of Grids or used CommonGrids. I don't have any examples on how to use them, so I have to read the tests.

[charleskawczynski]

I think we can address these in our docs page.

I think we need a bit more of a short over-arching story showing a UML diagram of everything that builds up to a space. From there we can expand onto fields / operators.

[charleskawczynski]

It might be nice if we could automatically generate a UML from objects. It's a bit difficult to do this in the sense that there are many many objects in a space, but if we filter objects at a certain depth, I think we can make something reasonable. For example, using StructuredPrinting.jl:

import ClimaCore
using ClimaCore.CommonSpaces
space = ExtrudedCubedSphereSpace(;
    z_elem = 10,
    z_min = 0,
    z_max = 1,
    radius = 10,
    h_elem = 10,
    n_quad_points = 4,
    staggering = Grids.CellCenter()
)

using StructuredPrinting
print_obj = x -> occursin("ClimaCore", string(parentmodule(typeof(x)))) && !(eltype(x) <: ClimaCore.Geometry.AxisTensor) && !(x isa ClimaCore.DataLayouts.AbstractData)
o = Options(; print_obj, max_type_depth = 1)
@structured_print space o

Which gives:

julia> import ClimaCore

julia> using ClimaCore.CommonSpaces

julia> space = ExtrudedCubedSphereSpace(;
           z_elem = 10,
           z_min = 0,
           z_max = 1,
           radius = 10,
           h_elem = 10,
           n_quad_points = 4,
           staggering = Grids.CellCenter()
       )
CenterExtrudedFiniteDifferenceSpace:
  context: SingletonCommsContext using CPUSingleThreaded
  horizontal:
    mesh: 10×10×6-element EquiangularCubedSphere of SphereDomain: radius = 10.0
    quadrature: 4-point Gauss-Legendre-Lobatto quadrature
  vertical:
    mesh: 10-element IntervalMesh of IntervalDomain: z ∈ [0.0,1.0] (:bottom, :top)

julia> using StructuredPrinting

julia> print_obj = x -> occursin("ClimaCore", string(parentmodule(typeof(x)))) && !(eltype(x) <: ClimaCore.Geometry.AxisTensor) && !(x isa ClimaCore.DataLayouts.AbstractData)
#1 (generic function with 1 method)

julia> o = Options(; print_obj, max_type_depth = 1)
Options{var"#1#2", Returns{Bool}, StructuredPrinting.var"#5#9", Returns{Bool}}(var"#1#2"(), Returns{Bool}(false), StructuredPrinting.var"#5#9"(), Returns{Bool}(true), 1000, 1)

julia> @structured_print space o
space
space.grid::ClimaCore.Grids.ExtrudedFiniteDifferenceGrid{…}
space.grid.horizontal_grid::ClimaCore.Grids.SpectralElementGrid2D{…}
space.grid.horizontal_grid.topology::ClimaCore.Topologies.Topology2D{…}
space.grid.horizontal_grid.topology.mesh::ClimaCore.Meshes.EquiangularCubedSphere{…}
space.grid.horizontal_grid.topology.mesh.domain::ClimaCore.Domains.SphereDomain{…}
space.grid.horizontal_grid.topology.mesh.localelementmap::ClimaCore.Meshes.NormalizedBilinearMap
space.grid.horizontal_grid.quadrature_style::ClimaCore.Quadratures.GLL{…}
space.grid.horizontal_grid.global_geometry::ClimaCore.Geometry.SphericalGlobalGeometry{…}
space.grid.vertical_grid::ClimaCore.Grids.FiniteDifferenceGrid{…}
space.grid.vertical_grid.topology::ClimaCore.Topologies.IntervalTopology{…}
space.grid.vertical_grid.topology.mesh::ClimaCore.Meshes.IntervalMesh{…}
space.grid.vertical_grid.topology.mesh.domain::ClimaCore.Domains.IntervalDomain{…}
space.grid.vertical_grid.topology.mesh.domain.coord_min::ClimaCore.Geometry.ZPoint{…}
space.grid.vertical_grid.topology.mesh.domain.coord_max::ClimaCore.Geometry.ZPoint{…}
space.grid.vertical_grid.global_geometry::ClimaCore.Geometry.CartesianGlobalGeometry
space.grid.hypsography::ClimaCore.Grids.Flat
space.grid.global_geometry::ClimaCore.Geometry.ShallowSphericalGlobalGeometry{…}
space.staggering::ClimaCore.Grids.CellCenter

Some of these things are kind of internals, but it would be nice to somehow make a diagram of this so that new users understand the composition of a space.

[charleskawczynski]

Maybe we can use Kroki?

using Kroki

uml = ditaa"""
      +--------+
      |        |
      | Field  |
      |        |
      +--------+
      +--------+
      |        |
      | Space  |
      |        |
      +--------+
  +-------------+
  |             |
  |    Topology |
  |             |
  +-------------+
  +-------------+
  |             |
  |    Mesh     |
  |             |
  +-------------+
  +-------------+
  |             |
  |    Domain   |
  |             |
  +-------------+
"""