doc: update FORD docs and the README.md

README.md

@@ -25,7 +25,7 @@ Caffeine is a parallel runtime library that aims to support Fortran compilers wi
      `"--.__                   __.--"'
             `""-------------""'
 ```
-(Art from [ascii.co.uk].)
+Art from [ascii.co.uk].
 
 Prerequisites
 -------------
@@ -36,12 +36,11 @@ Caffeine leverages the following non-parallel features of Fortran to simplify th
 | The `iso_c_binding` module                | Fortran 2003  |
 | The `contiguous` attribute [1]            | Fortran 2008  |
 | `do concurrent` [2]                       | Fortran 2008  |
-| The ISO_Fortran_binding.h C header file   | Fortran 2018  |
+| The `ISO_Fortran_binding.h` C header file | Fortran 2018  |
 | Assumed-type dummy arguments: `type(*)`,  | Fortran 2018  |
 | Assumed-rank dummy arguments: `array(..)`,| Fortran 2018  |
 
 [1] This requirement simplifies development but might be removed in a future release.
-
 [2] This feature is used to support only `co_reduce` and might become optional in a future release.
 
 Download, build, and run an example
@@ -60,16 +59,17 @@ Run tests
 ./build/run-fpm.sh test
 ```
 
-Generate documentation
-----------------------
-Generate HTML documentation for Caffeine using [ford] as follows:
+Documentation
+-------------
+One of our continous integration (CI) scripts generates up-to-date Caffeine documentation using [ford].  The Ci script also deploys the generated documentation to [our GitHub Pages site].
+Alternatively, generate HTML documentation locally using [ford] as follows:
 ```
 ford doc-generator.md
 ```
 Open `doc/html/index.htmtl` in a web browser.
 
-Support and Development
------------------------
+Funding
+-------
 The Computer Languages and Systems Software ([CLaSS]) Group at [Berkeley Lab] leads Caffeine development under funding from the Exascale Computing Project ([ECP]).
 
 License
@@ -83,3 +83,4 @@ See [LICENSE.txt](LICENSE.txt) for usage terms and conditions.
 [ford]: https://github.com/Fortran-FOSS-Programmers/ford
 [MPI]: https://www.mpi-forum.org
 [ascii.co.uk]: https://ascii.co.uk/art/cup
+[site]: https://berkeleylab.github.io/caffeine

doc-generator.md

@@ -1,6 +1,6 @@
 ---
-project: Caffeine library 
-summary: A parallel runtime library supporting standard Fortran features.
+project: Caffeine
+summary: Library functions and derived types implementing the parallel features of Fortran 2018.
 src_dir: src/
 exclude_dir: doc
 output_dir: doc/html
@@ -12,4 +12,69 @@ display: public
          private
 source: true
 graph: true
+css: ford-docs.css
 md_extensions: markdown.extensions.toc
+coloured_edges: true
+sort: permission-alpha
+extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html
+            iso_c_binding:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fC_005fBINDING.html#ISO_005fC_005fBINDING
+lower: true
+print_creation_date: true
+creation_date: %Y-%m-%d %H:%M %z
+project_github: https://go.lbl.gov/caffeine
+project_download: https://github.com/berkeleylab/caffeine/releases
+author: Lawrence Berkeley National Laboratory
+email: [email protected]
+author_description: A U.S. Department of Energy National Laboratory Managed by the University of California
+author_pic: https://avatars.githubusercontent.com/u/18706005?s=200&v=4
+github: https://github.com/berkeleylab
+website: https://go.lbl.gov/class
+
+[TOC]
+
+@warning Caffeine is early-stage developmental software with evolving interfaces and functionality.
+
+Documentation
+=============
+
+Welcome to the Caffeine documentation.
+[FORD] generates this documentation from inline comments, static analysis, and Markdown files.
+The target audience for Caffeine is Fortran compiler developers.
+With a fully Caffeinated compiler, Fortran programmers can produce parallel executable files from standard Fortran with no need to directly reference Caffeine or any lower-level communication software.
+
+Philosophy and Motivations
+--------------------------
+* Write as much of Caffeine as possible in Fortran:
+    - Writing the runtime library in the language of the users increases the likelihood of community contributions.
+    - Writing the runtime library in Fortran obviates the need to directly manipulate compiler descriptors throughout much of Caffeine and allows Caffeine's underlying C layer to receive the Fortran-standard `CFI_cdesc_t` desriptor, which imwill make it easier to support multiple compilers.
+    - Writing most of Caffeine in Fortran offers the potential exploiting Fortran's rich array syntax, concurrent loop iterations (`do concurrent`), `pure` procedures and related features. Currently, these play a role only in one place: C callbacks to user-provided, `pure` functions that can be invoked inside a `do concurrent` block during the execution of `co_reduce`.
+* Define an interface that remains agnostic about the back-end communication library:
+    - Once multiple back ends are supported, Fortran developers would not have to rewrite or even recompile their programs in order to change back ends. Switching from GASNet-EX to MPI, for example, could become a link-time decision.
+
+Organization
+------------
+The tree below depicts a skeletal overview of Caffeine's directory structure.
+```
+build/ - build directory created by running ./install.sh
+  |-- run-fpm.sh - shell script for rebuilding Caffeine or running examples or tests
+  |-- * - temporary build files
+example/
+  |-- hello.f90 - a Caffeinated "Hello, world!" program
+  |-- support-test/ - programs invoked by the test suite
+src/
+  |-- caffeine_m.f90 - the Big Kahuna: one module that exports all Caffeine functionality
+  |-- caffeine/
+        |-- *_m.f90 - modules containing procedure interface bodies
+        |-- *_s.f90 - submodules containing procedure definitions
+        |-- *.c - thin C functions wrapping networking middleware
+        |-- *.h - corresponding C header files
+        |-- *_h_m.f90 - a Fortran translation of a C header file
+        |-- collective_subroutines/
+              |-- co_*_s.f90 - submodules containing procedure definitions
+test/
+  |-- main.f90 - test suite driver created by make_vegetable_driver
+  |-- *_test.f90 - unit tests
+
+```
+
+[FORD]: https://github.com/Fortran-FOSS-Programmers/ford#readme

ford-docs.css

@@ -0,0 +1,11 @@
+table {
+  border-collapse: collapse;
+}
+
+th, td {
+  padding: 8px;
+}
+
+tr:nth-child(even) {background-color: #f2f2f2;}
+
+#responsive-image {  width: 100%;  height: auto; }