Merge branch 'main' into develop

GEOS-ESM · Dec 1, 2023 · ca70961 · ca70961
2 parents 960ffc8 + 76ac64b
commit ca70961
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 13 deletions.
diff --git a/.github/actions/deploy-ford-docs/action.yml b/.github/actions/deploy-ford-docs/action.yml
@@ -37,6 +37,10 @@ runs:
       run: ford --version
       shell: bash
 
+    - name: cpp version
+      run: cpp --version
+      shell: bash
+
     - name: Checkout gFTL
       uses: actions/checkout@v3
       with:

diff --git a/docs/Ford/README.md b/docs/Ford/README.md
@@ -0,0 +1,33 @@
+# Ford Documentation
+
+These are control files for the [Ford documentation generator](https://github.com/Fortran-FOSS-Programmers/ford). MAPL currently has
+two:
+
+1. `docs-with-remote-esmf.md` - This is the main documentation file.  It
+   includes the documentation for MAPL and ESMF.  It is used to generate the
+   [MAPL documentation](https://geos-esm.github.io/MAPL/).
+2. `docs-with-remote-esmf.public_private_protected.md` - This generates the "developer" version of the MAPL documentation.  It includes
+   the documentation for MAPL and ESMF, but also includes the private and
+   protected members of the MAPL classes.  It is used to generate the
+   [developer version of the MAPL documentation](https://geos-esm.github.io/MAPL/dev-doc/).
+
+## Issue with `pcpp`
+
+Note that currently MAPL does not work with `pcpp` which is the default
+preprocessor for Ford 7.  Instead, we must use `cpp` with the `-traditional-cpp`
+flag.  This is done by setting the `preprocessor:` in the Ford markdown files.
+
+```markdown
+preprocessor: cpp -traditional-cpp -E
+```
+
+### cpp on macOS
+
+Note that on macOS, `cpp` is by default clang's preprocessor.  To use the GNU
+preprocessor, you must install it with Homebrew and then use the full path to
+the executable, e.g.,
+
+```markdown
+preprocessor: /opt/homebrew/bin/cpp-13 -traditional-cpp -E
+```
+
diff --git a/docs/Ford/docs-with-remote-esmf.md b/docs/Ford/docs-with-remote-esmf.md
@@ -1,4 +1,5 @@
 ---
+preprocessor: cpp -traditional-cpp -E
 src_dir: ../../
 search: true
 graph: true
@@ -8,12 +9,12 @@ graph_maxnodes: 32
 include: ../../include/
          ../../gFTL/install/GFTL-1.10/include/v1
          ../../gFTL/install/GFTL-1.10/include/v2
-exclude: EsmfRegridder.F90
-         FieldBLAS_IntrinsicFunctions.F90
-         GeomManager.F90
-         MaplGeom.F90
-         Regridder.F90
-         StateSupplement.F90
+exclude: **/EsmfRegridder.F90
+         **/FieldBLAS_IntrinsicFunctions.F90
+         **/GeomManager.F90
+         **/MaplGeom.F90
+         **/Regridder.F90
+         **/StateSupplement.F90
 exclude_dir: ../../docs
              ../../Doxygen
              ../../ESMA_cmake

diff --git a/docs/Ford/docs-with-remote-esmf.public_private_protected.md b/docs/Ford/docs-with-remote-esmf.public_private_protected.md
@@ -1,4 +1,5 @@
 ---
+preprocessor: cpp -traditional-cpp -E
 src_dir: ../../
 output_dir: dev-doc
 search: true
@@ -9,12 +10,12 @@ graph_maxnodes: 32
 include: ../../include/
          ../../gFTL/install/GFTL-1.10/include/v1
          ../../gFTL/install/GFTL-1.10/include/v2
-exclude: EsmfRegridder.F90
-         FieldBLAS_IntrinsicFunctions.F90
-         GeomManager.F90
-         MaplGeom.F90
-         Regridder.F90
-         StateSupplement.F90
+exclude: **/EsmfRegridder.F90
+         **/FieldBLAS_IntrinsicFunctions.F90
+         **/GeomManager.F90
+         **/MaplGeom.F90
+         **/Regridder.F90
+         **/StateSupplement.F90
 exclude_dir: ../../docs
              ../../Doxygen
              ../../ESMA_cmake
@@ -64,4 +65,4 @@ fpp_extensions: F90
 externalize: true
 ---
 
-{!../README.md!}
+{!../../README.md!}