Merge #269

269: Fix broken documentation, make strict r=charleskawczynski a=charleskawczynski Fixes #262 Co-authored-by: Charles Kawczynski <kawczynski.charles@gmail.com>
CliMA · Mar 19, 2021 · 92874df · 92874df
2 parents ce73302 + 5e91106
commit 92874df
Show file tree

Hide file tree

Showing 17 changed files with 62 additions and 124 deletions.
diff --git a/.buildkite/ci-pipeline.yml b/.buildkite/ci-pipeline.yml
@@ -8,10 +8,10 @@ steps:
       - "julia --color=yes --project -e 'using Pkg; Pkg.instantiate(;verbose=true)'"
       - "julia --color=yes --project test/runtests.jl"
     agents:
-      config: cpu 
+      config: cpu
       queue: central
       slurm_ntasks: 1
-      slurm_mem_per_cpu: 6G  
+      slurm_mem_per_cpu: 6G
 
   - label: "run units tests GPU"
     command:

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - trying
+      - staging
+    tags: '*'
+  pull_request:
+
+jobs:
+  docbuild:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: 1.5.4
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl
diff --git a/bors.toml b/bors.toml
@@ -2,6 +2,7 @@ status = [
   "test-os (ubuntu-latest)",
   "test-os (macos-latest)",
   "buildkite/rrtmgp-ci",
+  "docbuild",
 ]
 delete_merged_branches = true
 timeout_sec = 86400

diff --git a/docs/make.jl b/docs/make.jl
@@ -1,11 +1,9 @@
-Base.HOME_PROJECT[] = abspath(Base.HOME_PROJECT[]) # JuliaLang/julia/pull/28625
-
 using RRTMGP, Documenter, LaTeXStrings
 
 makedocs(
     sitename = "RRTMGP.jl",
     doctest = false,
-    strict = false,
+    strict = true,
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",
         mathengine = MathJax(Dict(
@@ -15,8 +13,8 @@ makedocs(
             ),
         )),
     ),
-    clean = false,
-    modules = [Documenter, RRTMGP],
+    clean = true,
+    modules = [RRTMGP],
     pages = Any[
         "Home"=>"index.md",
         "Mathematical Formulation"=>"MathFormulation.md",
@@ -27,7 +25,6 @@ makedocs(
             "References States" => "RRTMGP/ReferenceStates.md"
             "Source Functions" => "RRTMGP/SourceFunctions.md"
             "K-Distribution" => "RRTMGP/KDistribution.md"
-            "Mesh Orientation" => "MeshOrientation.md"
             "Atmospheric States" => "RRTMGP/AtmosphericStates.md"
             "Optical Properties" => "OpticalProps.md"
         ],

diff --git a/docs/src/MathFormulation.md b/docs/src/MathFormulation.md
@@ -74,18 +74,18 @@ Here, ``\F = \sum_i F_i``, with ``F_j = \FR{net} = \FR{+} - \FR{-}`` for some ``
 
 To solve for ``\FR{net}``, one must choose an approximation for optical properties. In `RRTMGP.jl`, choices include
 
- - [`OneScalar`](@ref OpticalProps.OneScalar): optical depth (``\τ{}``) only
- - [`TwoStream`](@ref OpticalProps.TwoStream): optical depth (``\τ{}``), single scattering albedo (``\SSA``), asymmetry factor (``\ASY``)
+ - [`OneScalar`]: optical depth (``\τ{}``) only
+ - [`TwoStream`]: optical depth (``\τ{}``), single scattering albedo (``\SSA``), asymmetry factor (``\ASY``)
 
-To compute either set of optical properties, one must call [`gas_optics!`](@ref GasOptics.gas_optics!) with the following arguments:
+To compute either set of optical properties, one must call [`gas_optics!`] with the following arguments:
 
- - A [K-Distribution](@ref) ``\KD``, `KDistributionLongwave` or `KDistributionShortwave`: typically read from [Data files](@ref)
- - An [`AtmosphericState`](@ref AtmosphericStates.AtmosphericState) ``\AS``, defined by: temperature ``\temperature``, pressure ``\pressure``, set of gas concentrations ([`AbstractGas`](@ref Gases.AbstractGas))
- - [optionally] An [`AbstractSourceFunc`](@ref SourceFunctions.AbstractSourceFunc) ``\FS``, `SourceFuncLongWave` or `SourceFuncShortWave`: source functions
+ - A [K-Distribution] ``\KD``, `KDistributionLongwave` or `KDistributionShortwave`: typically read from [Data files]
+ - An [`AtmosphericState`] ``\AS``, defined by: temperature ``\temperature``, pressure ``\pressure``, set of gas concentrations ([`AbstractGas`])
+ - [optionally] An [`AbstractSourceFunc`] ``\FS``, `SourceFuncLongWave` or `SourceFuncShortWave`: source functions
 
 Calling `GasOptics.gas_optics!` computes the optical depths via a 3D interpolation routine in the following simplified steps:
 
- - Initialize and compute [`InterpolationCoefficients`](@ref GasOptics.InterpolationCoefficients)
+ - Initialize and compute [`InterpolationCoefficients`]
  - Compute absorption optical depth ``\τ{absorption}`` for major and minor gas species (which has binary variation as a function of height `itropo=1,2`)
  - Compute Rayleigh scattering optical depth ``\τ{Rayleigh}``
  - Compute total optical depth: ``\τ{total} = \τ{absorption}+\τ{Rayleigh}``

diff --git a/docs/src/MeshOrientation.md b/docs/src/MeshOrientation.md
diff --git a/docs/src/OpticalProps.md b/docs/src/OpticalProps.md
@@ -1,25 +1,10 @@
 # Optical Properties
 
 ```@meta
-CurrentModule = RRTMGP.OpticalProps
+CurrentModule = RRTMGP.GrayOptics
 ```
 
 ```@docs
-AbstractOpticalProps
-AbstractOpticalPropsArry
-AbstractOpticalPropsPGP
-OpticalPropsBase
-OneScalar
-TwoStream
-OneScalarPGP
-TwoStreamPGP
+GrayOneScalar
+GrayTwoStream
 ```
-
-```@docs
-delta_scale!
-validate!
-increment!
-bands_are_equal
-gpoints_are_equal
-```
-
diff --git a/docs/src/RRTMGP/AtmosphericStates.md b/docs/src/RRTMGP/AtmosphericStates.md
@@ -1,18 +1,9 @@
 # Atmospheric State
 
 ```@meta
-CurrentModule = RRTMGP.AtmosphericStates
+CurrentModule = RRTMGP.GrayAtmosphericStates
 ```
 
 ```@docs
-AtmosphericState
-AtmosphericStatePGP
+GrayAtmosphericState
 ```
-
-```@docs
-get_col_dry
-extrap_lower
-extrap_upper
-interpolate_var
-```
-
diff --git a/docs/src/RRTMGP/GasConcs.md b/docs/src/RRTMGP/GasConcs.md
@@ -1,15 +1,3 @@
 # Gas Concentrations
 
-```@meta
-CurrentModule = RRTMGP.GasConcentrations
-```
-
-```@docs
-GasConcs
-GasConcsPGP
-```
-
-```@docs
-set_vmr!
-```
-
+To be added back in...
diff --git a/docs/src/RRTMGP/GasOptics.md b/docs/src/RRTMGP/GasOptics.md
@@ -1,21 +1,3 @@
 # Gas Optics
 
-```@meta
-CurrentModule = RRTMGP.GasOptics
-```
-
-```@docs
-GasOpticsAux
-GasOpticsVars
-AbstractGasOptics
-KDistributionLongwave
-KDistributionShortwave
-InterpolationCoefficients
-InterpolationCoefficientsPGP
-```
-
-```@docs
-gas_optics!
-get_k_dist_lw
-get_k_dist_sw
-```
+To be added back in...
diff --git a/docs/src/RRTMGP/Gases.md b/docs/src/RRTMGP/Gases.md
@@ -1,8 +1,3 @@
 # Gases
 
-```@meta
-CurrentModule = RRTMGP.Gases
-```
-```@docs
-AbstractGas
-```
+To be added back in...
diff --git a/docs/src/RRTMGP/ReferenceStates.md b/docs/src/RRTMGP/ReferenceStates.md
@@ -1,11 +1,3 @@
 # Reference State
 
-```@meta
-CurrentModule = RRTMGP.ReferenceStates
-```
-
-```@docs
-ReferenceState
-get_press_min
-```
-
+To be added back in...
diff --git a/docs/src/RRTMGP/SourceFunctions.md b/docs/src/RRTMGP/SourceFunctions.md
@@ -1,12 +1,10 @@
 # Source Functions
 
 ```@meta
-CurrentModule = RRTMGP.SourceFunctions
+CurrentModule = RRTMGP.GraySources
 ```
 
 ```@docs
-AbstractSourceFunc
-SourceFuncLongWave
-SourceFuncLongWavePGP
-SourceFuncShortWave
+GraySourceLWNoScat
+GraySourceLW2Str
 ```
diff --git a/docs/src/RTE/AngularDiscretizations.md b/docs/src/RTE/AngularDiscretizations.md
@@ -1,9 +1,9 @@
 # Angular Discretization
 
 ```@meta
-CurrentModule = RRTMGP.AngularDiscretizations
+CurrentModule = RRTMGP.GrayAngularDiscretizations
 ```
 
 ```@docs
-GaussQuadrature
+AngularDiscretization
 ```
diff --git a/docs/src/RTE/BoundaryConditions.md b/docs/src/RTE/BoundaryConditions.md
@@ -1,11 +1,13 @@
 # Boundary Conditions
 
 ```@meta
-CurrentModule = RRTMGP.RadiativeBoundaryConditions
+CurrentModule = RRTMGP.GrayBCs
 ```
 
 ```@docs
-AbstractRadiativeBoundaryConditions
-ShortwaveBCs
-LongwaveBCs
+GrayLwBCs
+GraySwBCs
 ```
+
+│     RRTMGP.GraySources.GraySourceLWNoScat
+│     RRTMGP.GraySources.GraySourceLW2Str
diff --git a/docs/src/RTE/Fluxes.md b/docs/src/RTE/Fluxes.md
@@ -1,16 +1,9 @@
 # Fluxes
 
 ```@meta
-CurrentModule = RRTMGP.Fluxes
+CurrentModule = RRTMGP.GrayFluxes
 ```
 
 ```@docs
-AbstractFluxes
-FluxesBroadBand
-FluxesByBand
+GrayFluxLW
 ```
-
-```@docs
-reduce!
-```
-
diff --git a/docs/src/RTE/RTESolver.md b/docs/src/RTE/RTESolver.md
@@ -1,13 +1,10 @@
 # RTE Solver
 
 ```@meta
-CurrentModule = RRTMGP.RTESolver
+CurrentModule = RRTMGP.GrayRTESolver
 ```
 
 ```@docs
-rte_sw!
-rte_lw!
-expand_and_transpose
 ```