Documentation -> develop (#241)

Update develop branch with changes in documentation branch

Compiler-flags.md

@@ -8,26 +8,37 @@ To build any of the executables in `examples/` or `tests` the locations of the C
 need to be set via environment variables `NCHOME` and `NFHOME`, and the variable `RRTMGP_ROOT` must be set to the
 root of the RTE+RRTMGP installation.
 
-## Gnu Fortran
-`FC: gfortran-8` or `gfortran-9` or `gfortran-10`
+## Gnu Fortran 
+(see also the [continuous integration](https://github.com/earth-system-radiation/rte-rrtmgp/blob/main/.github/workflows/continuous-integration.yml))
+`FC: `gfortran-10` or `gfortran-11` or `gfortran-12`
 ### Debugging flags
 `FCFLAGS: "-ffree-line-length-none -m64 -std=f2008 -march=native -fbounds-check -finit-real=nan -DRTE_USE_CBOOL"`  
 ### Even stricter debugging flags
 `FCFLAGS: "-ffree-line-length-none -m64 -std=f2008 -march=native -fbounds-check -fbacktrace -finit-real=nan -DRTE_USE_CBOOL -pedantic -g -Wall"`  
 
-## Intel Fortran
+## Intel Fortran Classic 
+(see also the [continuous integration](https://github.com/earth-system-radiation/rte-rrtmgp/blob/main/.github/workflows/containerized-ci.yml))
 `FC: ifort`  
 ### Debugging flags
 `FCFLAGS: "-m64 -g -traceback -heap-arrays -assume realloc_lhs -extend-source 132 -check bounds,uninit,pointers,stack -stand f08"`  
 ### Optimization flags:  
 `FCFLAGS:"-m64 -O3 -g -traceback -heap-arrays -assume realloc_lhs -extend-source 132"`
 
+## Intel Fortran 
+(LLVM, see also the [continuous integration](https://github.com/earth-system-radiation/rte-rrtmgp/blob/main/.github/workflows/containerized-ci.yml))
+`FC: ifort`  
+### Debugging flags
+`FCFLAGS: "-debug -traceback -heap-arrays -assume realloc_lhs -extend-source 132 -stand f08"`  
+### Using OpenMP GPU offload 
+See [this open issue](https://github.com/earth-system-radiation/rte-rrtmgp/issues/194)
+
 ## NVFortran
-`FC: nvfortran` (if using the Nvidia HPC SDK)
+(see also the see also the [continuous integration](https://github.com/earth-system-radiation/rte-rrtmgp/blob/main/.github/workflows/containerized-ci.yml))
+`FC: nvfortran`
 ### Debugging flags
 `FCFLAGS: "-g -Minfo -Mbounds -Mchkptr -Mstandard -Kieee -Mchkstk -Mallocatable=03  -Mpreprocess"`
 ### Optimization flags:  
-`FCFLAGS: "-g -O3 -fast -Minfo -Mallocatable=03 -Mpreprocess"`
+`FCFLAGS: "-O3 -fast -Minfo -Mallocatable=03 -Mpreprocess"`
 
 ## HPE CCE for GPU using OpenMP-acc: crayftn   -- requires at least CCE 14.0.0
 `FC: crayftn`

doc/ford_site/rrtmgp-fortran-interface.md

@@ -36,9 +36,9 @@ The user interface uses the [ty_gas_concs](./module/mo_gas_concentrations.html)
 to represent the volume mixing ratios needed as input. Output suitable for
 scattering emission, two-stream, or multi-stream calculations are provided
 depending on which sub-class of RTE's
-[ty_optical_props_arry](./rte-fortran-interface/module/mo_optical_props.html#type-ty_optical_props_arry)
+[ty_optical_props_arry](../rte-fortran-interface/module/mo_optical_props.html#type-ty_optical_props_arry)
 are provided. Planck source functions, if requested, are reported in a variable
-of type [ty_source_func_lw.](./rte-fortran-interface/type/ty_source_func_lw.html)
+of type [ty_source_func_lw.](../rte-fortran-interface/type/ty_source_func_lw.html)
 
 The listings below may not be exhaustive.
 To see the full listings use the links at the top of the page.
@@ -47,4 +47,3 @@ There is a search bar in the top right.
 Return to the [Documentation overview] or the [reference overview].
 
 [Documentation overview]: ../../index.html
-[reference overview]: ../../reference.html

doc/ford_site/rrtmgp-kernels.md

@@ -24,4 +24,4 @@ There is a search bar in the top right.
 Return to the [Documentation overview] or the [reference overview].
 
 [Documentation overview]: ../../index.html
-[reference overview]: ../../reference.html
+[reference overview]:    ../index.html

doc/ford_site/rte-fortran-interface.md

@@ -10,6 +10,7 @@ author: The RTE+RRTTMGP consortium
 github: https://github.com/earth-system-radiation/
 license: by
 title: RTE Fortran interfaces-frontend
+src_dir: ../../rte-frontend
 output_dir: ../../public/reference/rte-fortran-interface
 ...
 
@@ -39,7 +40,7 @@ There is a search bar in the top right.
 Return to the [Documentation overview] or the [reference overview].
 
 [Documentation overview]: ../../index.html
-[reference overview]: ../../reference.html
+[reference overview]:    ../index.html
 
 <!---
 ## How to Read This Documentation

doc/ford_site/rte-kernels.md

@@ -24,4 +24,4 @@ There is a search bar in the top right.
 Return to the [Documentation overview] or the [reference overview].
 
 [Documentation overview]: ../../index.html
-[reference overview]: ../../reference.html
+[reference overview]:    ../index.html

doc/jekyll_site/how-tos/index.md

@@ -4,29 +4,18 @@ title: "How-to guides"
 ---
 # How-to guides will live here
 
-## How to: build and test the libraries and examples
+## How-to: build, run, and test the libraries, examples, and unit-testing codes.
+
+1. Set environment variables `FC` (the Fortran 2003 compiler) and `FCFLAGS` (compiler flags). Examples are provided in the `Compiler-flags.md` file.
+2. Set environment variables `RRTMGP_ROOT` to the top-level RTE+RRTMGP directory and `RTE_KERNELS` to `accel` if you want the OpenACC/OpenMP kernels rather than the default.
+3. `make libs` in the top-level directory will make the RTE and RRTMGP libraries.
+4. The examples and testing codes use netCDF. Set the variables `NCHOME` and `NFHOME` to the roots of the C and Fortran netCDF installations. 
+5. Download the RRTMGP data either by cloning the [data repository](https://github.com/earth-system-radiation/rrtmgp-data) or from the [Zenodo archive](https://doi.org/10.5281/zenodo.7988260). Set the environment variable `RRTMGP_DATA` to the root of this directory. 
+6. `make tests` to will build and run the test. 
+7. Evaluating the results of the tests requires `Python` and the packages described in `environment.yml`. Comparisons can be made with `make check` in the top level directory. 
+8. `make` invoked without a target in the top level attempts all three steps.
 
-### Building and testing using (Gnu) make
 
-1. Set environment variables `FC` (the Fortran 2003 compiler) and `FCFLAGS` (compiler flags).
-   Examples are provided in the `Compiler-flags.md` file.
-2. Set environment variable `RRTMGP_ROOT` to the top-level RTE+RRTMGP directory.
-   Set the variables `NCHOME` and `NFHOME` to the roots of the C and Fortran
-   netCDF installations. (Building the libraries alone )
-3. Set environment variable `RTE_KERNELS` to `accel` if you want the OpenACC/OpenMP
-   kernels rather than the default.
-4. `make libs` in the top-level directory will make the RTE and RRTMGP libraries
-   and the regression tests in in `examples/` and `tests/`. Libraries and module
-   files are in `build/`; examples and tests are in the subdirectory containing
-   their source code.
-5. `make tests` runs the examples and regression tests.
-   (A few files need to be downloaded for `examples/rfmip-clear-sky`. The default
-   is to download with a Python script is shell script using `wget` is also available.)
-6. Comparisons can be made with `make check` in the top level directory.
-   Evaluating the results of the tests requires `Python` and the packages
-   described in `environment.yml`. One approach is to use
-   `conda env create -f environment.yml; conda activate rte_rrtmgp_test; make check`  
-7. `make` invoked without a target in the top level attempts all three steps.
 
 ### Building and testing using (Gnu) make
 

doc/jekyll_site/index.markdown

@@ -7,7 +7,10 @@ title: "RTE+RRTMGP documentation"
 This is the documentation for RTE+RRTMGP, a set of codes for computing radiative
 fluxes in planetary atmospheres. RTE+RRTMGP is described in a
 [paper](https://doi.org/10.1029/2019MS001621) in
-[Journal of Advances in Modeling Earth Systems](http://james.agu.org).
+[Journal of Advances in Modeling Earth Systems](http://james.agu.org). 
+The code itself can be sited as 
+doi:[10.5281/zenodo.3403172](https://doi.org/10.5281/zenodo.3403172) or via the 
+DOI attached to each release.
 
 RRTMGP uses a k-distribution to provide an optical description (absorption and
   possibly Rayleigh optical depth) of the gaseous atmosphere, along with the
@@ -30,3 +33,6 @@ and produce [tutorials](./tutorials/index.html), [how-to guides](./how-tos/index
 We are starting with the [reference documentation](./reference/index.html),
 auto-generated from the code itself. This is provided separately for
 RTE and RRTMGP and for the user-facing classes and underlying computational kernels.
+
+We welcome contributions to the documentation via pull requests to the `documentation` branch 
+of the Github repository. 

doc/jekyll_site/reference/index.md

@@ -14,6 +14,7 @@ RTE aspires to follow a set of coding conventions:
     and spectral quadrature point.
 - RTE and RRTMGP are agnostic to vertical ordering
 - Units are MKS
+- Procedures (with the exception of testing code) do not perform I/O 
 
 ## Fortran user-facing class interfaces