Merge pull request #457 from SpeedyWeather/mk/docstructure

Restructuring the docs
SpeedyWeather · Feb 24, 2024 · 50bd5af · 50bd5af
2 parents 75b7123 + 306dbfe
commit 50bd5af
Show file tree

Hide file tree

Showing 14 changed files with 52 additions and 70 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -9,19 +9,39 @@ makedocs(
     modules = [SpeedyWeather],
     pages = ["Home"=>"index.md",
             "Installation"=>"installation.md",
-            "How to run SpeedyWeather.jl"=>"how_to_run_speedy.md",
-            "Model setups"=>"setups.md",
-            "Spherical Harmonic Transform"=>"spectral_transform.md",
-            "Grids"=>"grids.md",
-            "Barotropic model"=>"barotropic.md",
-            "Shallow water model"=>"shallowwater.md",
-            "Primitive equation model"=>"primitiveequation.md",
-            "Parameterizations"=>"parameterizations.md",
-            "Extending SpeedyWeather"=>"extending.md",
-            "NetCDF output"=>"output.md",
-            "Submodule: RingGrids"=>"ringgrids.md",
-            "Submodule: LowerTriangularMatrices"=>"lowertriangularmatrices.md",
-            "Submodule: SpeedyTransforms"=>"speedytransforms.md",
+            "Dynamics" => [
+                "Barotropic model"=>"barotropic.md",
+                "Shallow water model"=>"shallowwater.md",
+                "Primitive equation model"=>"primitiveequation.md",
+            ],
+            "Physics" => [
+                "Large-scale condensation"=>"large_scale_condensation.md",
+                "Convection"=>"convection.md",
+                "Radiation"=>"radiation.md",
+                "Vertical diffusion"=>"vertical_diffusion.md",
+                "Surface fluxes"=>"surface_fluxes.md",
+            ],
+            "Discretization" => [
+                "Spherical Harmonic Transform"=>"spectral_transform.md",
+                "Grids"=>"grids.md",
+            ],
+            "Running SpeedyWeather" => [
+                "How to run SpeedyWeather"=>"how_to_run_speedy.md",
+                "Model setups"=>"setups.md",
+                "NetCDF output"=>"output.md",
+            ],
+            "Extending SpeedyWeather" => [
+                "Forcing and drag"=>"forcing_drag.md",
+                "Parameterizations"=>"parameterizations.md",
+                "Orography"=>"orography.md",
+                "Land-Sea Mask"=>"land_sea_mask.md",
+                "Callbacks"=>"callbacks.md",
+            ],
+            "Submodules" => [
+                "RingGrids"=>"ringgrids.md",
+                "LowerTriangularMatrices"=>"lowertriangularmatrices.md",
+                "SpeedyTransforms"=>"speedytransforms.md",
+            ],
             "Function and type index"=>"functions.md"]
 )
 

diff --git a/docs/src/callbacks.md b/docs/src/callbacks.md
@@ -0,0 +1,3 @@
+# Callbacks
+
+More to follow...
diff --git a/docs/src/convection.md b/docs/src/convection.md
@@ -0,0 +1,3 @@
+# Convection
+
+More to follow...
diff --git a/docs/src/extending.md → docs/src/forcing_drag.md b/docs/src/extending.md → docs/src/forcing_drag.md
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -22,31 +22,6 @@ SpeedyWeather.jl defines
 
 and solves these equations in spherical coordinates as described in this documentation.
 
-## Manual outline
-
-See the following pages of the documentation for more details
-
-- [Installation](installation.md)
-- [How to run SpeedyWeather.jl](how_to_run_speedy.md)
-- [Model setups](setups.md)
-- [Spherical harmonic transform](spectral_transform.md)
-- [Grids](grids.md)
-- [Barotropic model](barotropic.md)
-- [Shallow water model](shallowwater.md)
-- [Primitive equation model](primitiveequation.md)
-- [Parameterizations](parameterizations.md)
-- [Extending SpeedyWeather](extending.md)
-- [NetCDF output](output.md)
-
-and the submodules
-
-- [RingGrids](@ref)
-- [LowerTriangularMatrices](@ref lowertriangularmatrices)   
-- [SpeedyTransforms](@ref)
-
-and the [original documentation](http://users.ictp.it/~kucharsk/speedy_description/km_ver41_appendixA.pdf)
-by Molteni and Kucharski.
-
 ## Developers
 
 The development of  SpeedyWeather.jl is lead by [Milan Klöwer](https://github.com/milankl) and

diff --git a/docs/src/land_sea_mask.md b/docs/src/land_sea_mask.md
diff --git a/docs/src/large_scale_condensation.md b/docs/src/large_scale_condensation.md
@@ -0,0 +1,3 @@
+# Large-scale condensation
+
+more to follow ...
diff --git a/docs/src/orography.md b/docs/src/orography.md
diff --git a/docs/src/parameterizations.md b/docs/src/parameterizations.md
@@ -1,31 +1,3 @@
-# [Parameterizations](@id parameterizations)
+# Parameterizations
 
-This page describes the mathematical formulation of the parameterizations used in SpeedyWeather.jl to represent physical processes in the atmosphere. Every section is followed by a brief description of implementation details.
-
-## Convection
-
-more to come ...
-
-## Large-scale condensation
-
-more to come ...
-
-## Clouds
-
-more to come ...
-
-## Short-wave radiation
-
-more to come ...
-
-## Long-wave radiation
-
-more to come ...
-
-## Surface fluxes of momentum and energy
-
-more to come ...
-
-## Vertical diffusion
-
-more to come ...
+More to follow ...
diff --git a/docs/src/primitiveequation.md b/docs/src/primitiveequation.md
@@ -30,7 +30,7 @@ here for clarity, see [Horizontal diffusion](@ref diffusion).
 
 The parameterizations for the tendencies of ``u,v,T,q`` from physical processes are denoted as
 ``\mathcal{P}_\mathbf{u} = (\mathcal{P}_u, \mathcal{P}_v), \mathcal{P}_T, \mathcal{P}_q``
-and are further described in the corresponding sections, see [Parameterizations](@ref parameterizations).
+and are further described in the corresponding sections, see [Parameterizations](@ref).
 
 SpeedyWeather.jl implements a `PrimitiveWet` and a `PrimitiveDry` dynamical core.
 For a dry atmosphere, we have ``q = 0`` and the virtual temperature ``T_v = T``

diff --git a/docs/src/radiation.md b/docs/src/radiation.md
diff --git a/docs/src/spectral_transform.md b/docs/src/spectral_transform.md
@@ -235,7 +235,7 @@ There are many ways to estimate the effective grid resolution of spectral models
 Some of them are based on the wavelength a given spectral resolution allows to
 represent, others on the total number of real variables per area.
 However, as many atmospheric models do represent a considerable amount of physics
-on the grid (see [Parameterizations](@ref parameterizations)) there is also a good argument to
+on the grid (see [Parameterizations](@ref)) there is also a good argument to
 include the actual grid resolution into this estimate and not just the spectral
 resolution. We therefore use the average grid cell area to estimate the
 resolution

diff --git a/docs/src/surface_fluxes.md b/docs/src/surface_fluxes.md
@@ -0,0 +1,3 @@
+# Surface fluxes
+
+More to follow ... 
diff --git a/docs/src/vertical_diffusion.md b/docs/src/vertical_diffusion.md
@@ -0,0 +1,3 @@
+# Vertical Diffusion
+
+More to follow ...