From 7ee1c498ccf433a49768e9bd717b5373a623fb28 Mon Sep 17 00:00:00 2001 From: Damian Rouson Date: Tue, 1 Mar 2022 22:57:56 -0800 Subject: [PATCH] doc: update FORD docs and the README.md --- README.md | 17 ++++++------ doc-generator.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++-- ford-docs.css | 11 ++++++++ 3 files changed, 87 insertions(+), 10 deletions(-) create mode 100644 ford-docs.css diff --git a/README.md b/README.md index c68171036..fce80f92f 100644 --- a/README.md +++ b/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 diff --git a/doc-generator.md b/doc-generator.md index 7ee5d0a80..757d213de 100644 --- a/doc-generator.md +++ b/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: rouson@lbl.gov +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 diff --git a/ford-docs.css b/ford-docs.css new file mode 100644 index 000000000..a71897e09 --- /dev/null +++ b/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; }