Documentation website updates (earth-system-radiation#179)

More substantive content in the Jekyll pages, RTE kernels in-line documentation complete (merging from develop)

Author: RobertPincus

.gitignore

@@ -35,3 +35,6 @@ examples/*/*/*.nc
 
 # gh-pages directory
 public
+
+# Ruby stuff
+Gemfile.lock

doc/ford_site/pages/Organized_Listing.md

@@ -1,12 +1,14 @@
 ---
 project: RRTMGP-Fortran
 summary: RRTMGP is a correlated k-distribution for computing fluxes in earth's atmosphere.
-email: [email protected]
 preprocessor: gfortran -E
 display: public
 sort: permission-alpha
 graph: true
 md_extensions: markdown.extensions.toc
+author: The RTE+RRTTMGP consortium
+github: https://github.com/earth-system-radiation/
+license: by
 title: RRTMGP Fortran interfaces
 src_dir: ../../rrtmgp
 exclude_dir: ../../rrtmgp/kernels
@@ -16,16 +18,11 @@ output_dir: ../../public/reference/rrtmgp-fortran-interface
 
 These pages describe the Fortran user interface to RTE.
 
-## How to Read This Documentation
-
-Start with the [README] and the [Tutorial](./page/Tutorial.html).
-Additionally, there is a page that provides a higher level organizational overview that you can find [here](./page/Organized_Listing.html).
-
-The listings below are not exhaustive.
+The listings below may not be exhaustive.
 To see the full listings use the links at the top of the page.
-Also, if you know what you're looking for, there is a search bar in the top right.
+There is a search bar in the top right.
 
-Take me back to the [User Documentation].
+Return to the [Documentation overview] or the [reference overview].
 
-[README]: https://github.com/earth-system-radiation/rte-rrtmgp/blob/main/README.md
-[User Documentation]: ../../index.html
+[Documentation overview]: ../../index.html
+[reference overview]: ../../reference.html

doc/ford_site/pages/Tutorial.md

@@ -1,29 +1,26 @@
 ---
 project: RRTMGP kernels
 summary: RRTMGP is a correlated k-distribution for computing fluxes in earth's atmosphere.
-email: [email protected]
 preprocessor: gfortran -E
 display: public
 sort: permission-alpha
 graph: true
 md_extensions: markdown.extensions.toc
+author: The RTE+RRTTMGP consortium
+github: https://github.com/earth-system-radiation/
+license: by
 title: RRTMGP kernels
 src_dir: ../../rrtmgp/kernels
 output_dir: ../../public/reference/rrtmgp-kernels
 ...
 
 These pages document the low-level computational kernels used by RRTMGP.
 
-## How to Read This Documentation
-
-Start with the [README] and the [Tutorial](./page/Tutorial.html).
-Additionally, there is a page that provides a higher level organizational overview that you can find [here](./page/Organized_Listing.html).
-
 The listings below may not be exhaustive.
 To see the full listings use the links at the top of the page.
-If you know what you're looking for, there is a search bar in the top right.
+There is a search bar in the top right.
 
-Take me back to the [User Documentation].
+Return to the [Documentation overview] or the [reference overview].
 
-[README]: https://github.com/earth-system-radiation/rte-rrtmgp/blob/main/README.md
-[User Documentation]: ../../index.html
+[Documentation overview]: ../../index.html
+[reference overview]: ../../reference.html

doc/ford_site/pages/index.md

@@ -1,12 +1,14 @@
 ---
 project: RTE-Fortran
 summary: RTE describes radiation problems in planetary atmospheres and computes radiative fluxes.
-email: [email protected]
 preprocessor: gfortran -E
 display: public
 sort: permission-alpha
 graph: true
 md_extensions: markdown.extensions.toc
+author: The RTE+RRTTMGP consortium
+github: https://github.com/earth-system-radiation/
+license: by
 title: RTE Fortran interfaces
 src_dir: ../../rte
 exclude_dir: ../../rte/kernels
@@ -22,17 +24,6 @@ along with boundary conditions and/or [internal sources](./module/mo_source_func
 The reduction of spectrally- and spatially-detailed calculations that specifies the output
 is defined in a [flux output type](./module/mo_fluxes.html)
 
-RTE aspires to follow a set of coding conventions:
-
-- Module names start with `mo_`, class/type names with `ty_`.
-- Real variables are defined with working precision `wp`; logical variables with `wl`.
-    Both Fortran KIND parameters are set in [mo_rte_kind.F90]
-- Most procedures in RTE and RRTMGP are functions which return a string. A non-empty string indicates an error of some kind.
-- RTE and RRTMGP operate on multiple columns (profiles) at once. Problems are dimensioned by column, layer,
-    and spectral quadrature point.
-- RTE and RRTMGP are agnostic to vertical ordering
-- Units are MKS
-
 The optical properties module provides a way to specify the spectrally-dependent
 optical properties of the atmosphere consistent with calculations neglecting scattering,
 using two-stream scattering, or using n-stream scattering.
@@ -42,7 +33,16 @@ using two-stream scattering, or using n-stream scattering.
 - `alloc()` routines to allocate memory once the problem size is known
 - `finalize()` routines to reset variables to an un-initialized state
 - Some classes have `get_ncol()` and `get_nlay()` methods to report the problem size
-- Some classes have get_subset() methods to extract values along the column dimension
+- Some classes have `get_subset()` methods to extract values along the column dimension
+
+The listings below may not be exhaustive.
+To see the full listings use the links at the top of the page.
+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
 
 <!---
 ## How to Read This Documentation

doc/ford_site/rrtmgp-fortran-interface.md

@@ -1,29 +1,26 @@
 ---
 project: RTE kernels
 summary: RTE describes radiation problems in planetary atmospheres and computes radiative fluxes.
-email: [email protected]
 preprocessor: gfortran -E
 display: public
 sort: permission-alpha
 graph: true
 md_extensions: markdown.extensions.toc
+author: The RTE+RRTTMGP consortium
+github: https://github.com/earth-system-radiation/
+license: by
 title: RTE kernels
 src_dir: ../../rte/kernels
 output_dir: ../../public/reference/rte-kernels
 ...
 
 These pages document the low-level computational kernels used by RRTMGP.
 
-## How to Read This Documentation
-
-Start with the [README] and the [Tutorial](./page/Tutorial.html).
-Additionally, there is a page that provides a higher level organizational overview that you can find [here](./page/Organized_Listing.html).
-
 The listings below are not exhaustive.
 To see the full listings use the links at the top of the page.
-Also, if you know what you're looking for, there is a search bar in the top right.
+There is a search bar in the top right.
 
-Take me back to the [User Documentation].
+Return to the [Documentation overview] or the [reference overview].
 
-[README]: https://github.com/earth-system-radiation/rte-rrtmgp/blob/main/README.md
-[User Documentation]: ../../index.html
+[Documentation overview]: ../../index.html
+[reference overview]: ../../reference.html

doc/ford_site/rrtmgp-kernels.md

@@ -8,7 +8,7 @@
 # For technical reasons, this file is *NOT* reloaded automatically when you use
 # 'bundle exec jekyll serve'. If you change this file, please restart the server process.
 #
-# If you need help with YAML syntax, here are some quick references for you: 
+# If you need help with YAML syntax, here are some quick references for you:
 # https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
 # https://learnxinyminutes.com/docs/yaml/
 #
@@ -19,15 +19,19 @@
 # in the templates via {{ site.myvariable }}.
 
 title: RTE-RRTMGP
-email: your-email@example.com
+email: rrtmgp@aer.com
 description: >- # this means to ignore newlines until "baseurl:"
-  Write an awesome description for your new site here. You can edit this
-  line in _config.yml. It will appear in your document head meta (for
-  Google search results) and in your feed.xml site description.
+  RTE+RRTMGP is a set of codes for computing radiative fluxes in
+  planetary atmospheres. RRTMGP uses a k-distribution to provide an optical
+  description (absorption and possibly Rayleigh optical depth) of the gaseous
+  atmosphere, along with the relevant source functions, on a pre-determined
+  spectral grid given temperatures, pressures, and gas concentration.
+  RTE computes fluxes given spectrally-resolved optical descriptions and
+  source functions.
 baseurl: "/rte-rrtmgp" # the subpath of your site, e.g. /blog
-url: "https://sourceryinstitute.github.io/rte-rrtmgp/" # the base hostname & protocol for your site, e.g. http://example.com
+url: "https://earth-system-radiation.github.io/" # the base hostname & protocol for your site, e.g. http://example.com
 twitter_username: #jekyllrb
-github_username:  #jekyll
+github_username: earth-system-radiation
 
 # Build settings
 theme: minima
@@ -52,4 +56,4 @@ theme: minima
 #   - vendor/bundle/
 #   - vendor/cache/
 #   - vendor/gems/
-#   - vendor/ruby/
+#   - vendor/ruby/

doc/ford_site/rte-fortran-interface.md

@@ -0,0 +1,16 @@
+---
+layout: post
+title:  "2022-06-02: Release notes"
+categories: Release-notes
+---
+
+Commit [a4fe30c](https://github.com/earth-system-radiation/rte-rrtmgp/commit/a4fe30cf4dab2e5fd8d3ab6f11683a82ae584475) 
+to branch `main` makes the following changes:
+
+- Solar zenith angle can vary with height, allowing for calculations on a pseudo-spherical earth
+- New documentation site, partly hand-written (still essentially empty) and partly auto-generated from comments in code (partly complete).
+- Workaround for Intel compilers on specific AMD processors
+- Python dependencies made explicit in environment.yml files
+- Move from wget to Python for downloading files in testing
+- Public visibility and C-bindings restricted to just a few kernels
+- Assorted consistency and prettifying

doc/ford_site/rte-kernels.md

@@ -0,0 +1,12 @@
+---
+layout: "page"
+title: "Explanations"
+---
+
+# Explanations will live here
+
+### Spectral discretization
+
+The spectral properties of the atmosphere and the source functions depend on electromagnetic wavelength (or frequency or wavenumber). RTE treats this spectral dependence by dividing the spectrum into one or more _bands_, each of which represents a continuous set of wavelengths/frequencies. Bands may be further sub-divided into _g-points_ (the language is borrowed from _k_-distributions). Each _g_-point is treated as a independent psudo-monchromatic calculation but there is no inherent mapping between _g_-points and wavelengths; the sum over _g_-points is the band-average value.
+
+The bands defined by RRTMGP cover the full spectrum of radiation emitted by the Sun and Earth: these are _broadband_ calculations. In RRTMGP the bands are continuous so that the ending wavelength of one band is the starting wavelength of the next.  

doc/jekyll_site/Tutorials.md

@@ -1,6 +1,6 @@
 ---
 layout: "page"
-title: "How To's"
+title: "How-to guides"
 ---
 
-# This is a site for How To's
+# How-to guides will live here