Improve the documentation builds, including API docs (Exawind#1275)

.github/workflows/docs.yml

@@ -16,6 +16,8 @@ jobs:
     steps:
       - name: Clone
         uses: actions/checkout@v4
+        with:
+          submodules: true
       - name: Python
         uses: actions/setup-python@v5
         with:
@@ -24,27 +26,24 @@ jobs:
         run: |
           export DEBIAN_FRONTEND=noninteractive
           sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            doxygen graphviz libenchant-2-dev
+          sudo apt-get install -y --no-install-recommends graphviz libenchant-2-dev
           python3 -m pip install --upgrade pip
-          pip3 install sphinx sphinx_rtd_theme sphinx_toolbox sphinx_copybutton pyenchant sphinxcontrib-spelling
-      - name: Spellcheck
-        # execute from top-level amr-wind directory
+          pip3 install sphinx sphinx_rtd_theme sphinx_toolbox sphinx_copybutton pyenchant sphinxcontrib-spelling doxysphinx
+      - name: Doxygen install
+        uses: ssciwr/[email protected]
+        with:
+          version: "1.12.0"
+      - name: Configure
         run: |
-          echo "::add-matcher::.github/problem-matchers/sphinx.json"
-          sphinx-build -b spelling ./docs/sphinx ./build_docs/manual/spelling 2>&1 | tee -a build-output.txt
+          cmake -B ${{runner.workspace}}/build-docs \
+            -DAMR_WIND_ENABLE_DOCUMENTATION:BOOL=ON \
+            ${{github.workspace}}
       - name: Build
         # execute from top-level amr-wind directory
         run: |
           echo "::add-matcher::.github/problem-matchers/sphinx.json"
-          sphinx-build -M html ./docs/sphinx ./build_docs/manual -W --keep-going -n 2>&1 | tee -a build-output.txt
-          # Doxygen output gets parsed wrong by the sphinx problem matcher so unregister it
-          echo "::remove-matcher owner=sphinx-problem-matcher-loose-no-severity::"
-          echo "::remove-matcher owner=sphinx-problem-matcher-loose::"
-          echo "::remove-matcher owner=sphinx-problem-matcher::"
-          doxygen ./docs/doxygen/Doxyfile
-          mv ./build_docs/manual/html ./documentation
-          mv ./build_docs/doxygen/html ./documentation/api_docs
+          cmake --build ${{runner.workspace}}/build-docs -t docs 2>&1 | tee -a build-output.txt
+          mv ${{runner.workspace}}/build-docs/docs/sphinx/html ./documentation
           touch ./documentation/.nojekyll
       - name: Report
         run: |

.gitignore

@@ -22,4 +22,5 @@ settings.json
 .ccls
 .ccls-cache/
 build*
-__pycache__/
+__pycache__/
+docs/sphinx/doxygen

.gitmodules

@@ -10,3 +10,6 @@
 [submodule "submods/Waves2AMR"]
 	path = submods/Waves2AMR
 	url = https://github.com/Exawind/Waves2AMR.git
+[submodule "submods/doxygen-awesome-css"]
+	path = submods/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

CMakeLists.txt

@@ -15,6 +15,7 @@ option(AMR_WIND_ENABLE_ALL_WARNINGS "Show most warnings for most compilers" ON)
 option(AMR_WIND_ENABLE_CLANG_TIDY "Compile with clang-tidy static analysis" OFF)
 option(AMR_WIND_ENABLE_CPPCHECK "Enable cppcheck static analysis target" OFF)
 option(AMR_WIND_ENABLE_FCOMPARE "Enable building fcompare when not testing" OFF)
+option(AMR_WIND_ENABLE_DOCUMENTATION "Enable documentation target" OFF)
 
 #Enabling tests overrides the executable options
 option(AMR_WIND_ENABLE_UNIT_TESTS "Enable unit testing" ON)
@@ -237,6 +238,10 @@ if(AMR_WIND_ENABLE_TESTS)
   add_subdirectory(test)
 endif()
 
+if(AMR_WIND_ENABLE_DOCUMENTATION)
+  add_subdirectory(docs)
+endif()
+
 #Define what we want to be installed during a make install
 install(
   TARGETS ${amr_wind_exe_name}

README.md

@@ -1,6 +1,6 @@
 # AMR-Wind 
 
-[Documentation](https://exawind.github.io/amr-wind) | [API docs](https://exawind.github.io/amr-wind/api_docs) | [Nightly test dashboard](http://my.cdash.org/index.php?project=Exawind) 
+[Documentation](https://exawind.github.io/amr-wind) | [Nightly test dashboard](http://my.cdash.org/index.php?project=Exawind) 
 
 [![Powered by AMReX](https://amrex-codes.github.io/badges/powered%20by-AMReX-red.svg)](https://amrex-codes.github.io/amrex/) [![Build Status](https://github.com/Exawind/amr-wind/workflows/AMR-Wind-CI/badge.svg)](https://github.com/Exawind/amr-wind/actions) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9284/badge)](https://www.bestpractices.dev/projects/9284)
 
@@ -42,8 +42,8 @@ objectives:
 
 Documentation is available at https://exawind.github.io/amr-wind, which 
 includes a walkthrough tutorial, a user manual, notes on theory,
-and tips for developers. We also provide a developer-focused [API
-documentation](https://exawind.github.io/amr-wind/api_docs). You can either
+and tips for developers. We also provide a developer-focused API
+documentation at the same link. You can either
 browse the docs online by following the links, or you can generate them locally
 after downloading the code. Please follow the instructions in user manual to
 build documentation locally.

amr-wind/convection/incflo_mol_fluxes.cpp

@@ -3,16 +3,14 @@
 #include "amr-wind/convection/MOL.H"
 #include "amr-wind/utilities/bc_ops.H"
 
-using namespace amrex;
-
 void mol::compute_convective_rate(
-    Box const& bx,
+    amrex::Box const& bx,
     int ncomp,
-    Array4<Real> const& dUdt,
-    Array4<Real const> const& fx,
-    Array4<Real const> const& fy,
-    Array4<Real const> const& fz,
-    GpuArray<Real, AMREX_SPACEDIM> dxi)
+    amrex::Array4<amrex::Real> const& dUdt,
+    amrex::Array4<amrex::Real const> const& fx,
+    amrex::Array4<amrex::Real const> const& fy,
+    amrex::Array4<amrex::Real const> const& fz,
+    amrex::GpuArray<amrex::Real, AMREX_SPACEDIM> dxi)
 {
     BL_PROFILE("amr-wind::mol::compute_convective_rate");
     const auto dxinv = dxi;
@@ -27,38 +25,38 @@ void mol::compute_convective_rate(
 
 void mol::compute_convective_fluxes(
     int lev,
-    Box const& bx,
+    amrex::Box const& bx,
     int ncomp,
-    Array4<Real> const& fx,
-    Array4<Real> const& fy,
-    Array4<Real> const& fz,
-    Array4<Real const> const& q,
-    Array4<Real const> const& umac,
-    Array4<Real const> const& vmac,
-    Array4<Real const> const& wmac,
-    BCRec const* h_bcrec,
-    BCRec const* d_bcrec,
-    Vector<Geometry> geom)
+    amrex::Array4<amrex::Real> const& fx,
+    amrex::Array4<amrex::Real> const& fy,
+    amrex::Array4<amrex::Real> const& fz,
+    amrex::Array4<amrex::Real const> const& q,
+    amrex::Array4<amrex::Real const> const& umac,
+    amrex::Array4<amrex::Real const> const& vmac,
+    amrex::Array4<amrex::Real const> const& wmac,
+    amrex::BCRec const* h_bcrec,
+    amrex::BCRec const* d_bcrec,
+    amrex::Vector<amrex::Geometry> geom)
 {
     BL_PROFILE("amr-wind::mol::compute_convective_fluxes");
-    constexpr Real small_vel = 1.e-8;
+    constexpr amrex::Real small_vel = 1.e-8;
 
-    const Box& domain_box = geom[lev].Domain();
+    const amrex::Box& domain_box = geom[lev].Domain();
     const int domain_ilo = domain_box.smallEnd(0);
     const int domain_ihi = domain_box.bigEnd(0);
     const int domain_jlo = domain_box.smallEnd(1);
     const int domain_jhi = domain_box.bigEnd(1);
     const int domain_klo = domain_box.smallEnd(2);
     const int domain_khi = domain_box.bigEnd(2);
 
-    Box const& xbx = amrex::surroundingNodes(bx, 0);
-    Box const& ybx = amrex::surroundingNodes(bx, 1);
-    Box const& zbx = amrex::surroundingNodes(bx, 2);
+    amrex::Box const& xbx = amrex::surroundingNodes(bx, 0);
+    amrex::Box const& ybx = amrex::surroundingNodes(bx, 1);
+    amrex::Box const& zbx = amrex::surroundingNodes(bx, 2);
 
     // At an ext_dir boundary, the boundary value is on the face, not cell
     // center.
     auto extdir_lohi = amr_wind::utils::has_extdir_or_ho(
-        h_bcrec, ncomp, static_cast<int>(Direction::x));
+        h_bcrec, ncomp, static_cast<int>(amrex::Direction::x));
     bool has_extdir_lo = extdir_lohi.first;
     bool has_extdir_hi = extdir_lohi.second;
     if ((has_extdir_lo and domain_ilo >= xbx.smallEnd(0) - 1) or
@@ -67,24 +65,27 @@ void mol::compute_convective_fluxes(
             xbx, ncomp,
             [d_bcrec, q, domain_ilo, domain_ihi, umac,
              fx] AMREX_GPU_DEVICE(int i, int j, int k, int n) noexcept {
-                bool extdir_or_ho_ilo = (d_bcrec[n].lo(0) == BCType::ext_dir) ||
-                                        (d_bcrec[n].lo(0) == BCType::hoextrap);
-                bool extdir_or_ho_ihi = (d_bcrec[n].hi(0) == BCType::ext_dir) ||
-                                        (d_bcrec[n].hi(0) == BCType::hoextrap);
-                Real qs;
-                if (i <= domain_ilo && (d_bcrec[n].lo(0) == BCType::ext_dir)) {
+                bool extdir_or_ho_ilo =
+                    (d_bcrec[n].lo(0) == amrex::BCType::ext_dir) ||
+                    (d_bcrec[n].lo(0) == amrex::BCType::hoextrap);
+                bool extdir_or_ho_ihi =
+                    (d_bcrec[n].hi(0) == amrex::BCType::ext_dir) ||
+                    (d_bcrec[n].hi(0) == amrex::BCType::hoextrap);
+                amrex::Real qs;
+                if (i <= domain_ilo &&
+                    (d_bcrec[n].lo(0) == amrex::BCType::ext_dir)) {
                     qs = q(domain_ilo - 1, j, k, n);
                 } else if (
                     i >= domain_ihi + 1 &&
-                    (d_bcrec[n].hi(0) == BCType::ext_dir)) {
+                    (d_bcrec[n].hi(0) == amrex::BCType::ext_dir)) {
                     qs = q(domain_ihi + 1, j, k, n);
                 } else {
-                    Real qpls =
+                    amrex::Real qpls =
                         q(i, j, k, n) -
                         0.5 * amrex_calc_xslope_extdir(
                                   i, j, k, n, 2, q, extdir_or_ho_ilo,
                                   extdir_or_ho_ihi, domain_ilo, domain_ihi);
-                    Real qmns =
+                    amrex::Real qmns =
                         q(i - 1, j, k, n) +
                         0.5 * amrex_calc_xslope_extdir(
                                   i - 1, j, k, n, 2, q, extdir_or_ho_ilo,
@@ -104,11 +105,12 @@ void mol::compute_convective_fluxes(
             xbx, ncomp,
             [q, umac,
              fx] AMREX_GPU_DEVICE(int i, int j, int k, int n) noexcept {
-                Real qpls =
+                amrex::Real qpls =
                     q(i, j, k, n) - 0.5 * amrex_calc_xslope(i, j, k, n, 2, q);
-                Real qmns = q(i - 1, j, k, n) +
-                            0.5 * amrex_calc_xslope(i - 1, j, k, n, 2, q);
-                Real qs;
+                amrex::Real qmns =
+                    q(i - 1, j, k, n) +
+                    0.5 * amrex_calc_xslope(i - 1, j, k, n, 2, q);
+                amrex::Real qs;
                 if (umac(i, j, k) > small_vel) {
                     qs = qmns;
                 } else if (umac(i, j, k) < -small_vel) {
@@ -121,7 +123,7 @@ void mol::compute_convective_fluxes(
     }
 
     extdir_lohi = amr_wind::utils::has_extdir_or_ho(
-        h_bcrec, ncomp, static_cast<int>(Direction::y));
+        h_bcrec, ncomp, static_cast<int>(amrex::Direction::y));
     has_extdir_lo = extdir_lohi.first;
     has_extdir_hi = extdir_lohi.second;
     if ((has_extdir_lo and domain_jlo >= ybx.smallEnd(1) - 1) or
@@ -130,24 +132,27 @@ void mol::compute_convective_fluxes(
             ybx, ncomp,
             [d_bcrec, q, domain_jlo, domain_jhi, vmac,
              fy] AMREX_GPU_DEVICE(int i, int j, int k, int n) noexcept {
-                bool extdir_or_ho_jlo = (d_bcrec[n].lo(1) == BCType::ext_dir) ||
-                                        (d_bcrec[n].lo(1) == BCType::hoextrap);
-                bool extdir_or_ho_jhi = (d_bcrec[n].hi(1) == BCType::ext_dir) ||
-                                        (d_bcrec[n].hi(1) == BCType::hoextrap);
-                Real qs;
-                if (j <= domain_jlo && (d_bcrec[n].lo(1) == BCType::ext_dir)) {
+                bool extdir_or_ho_jlo =
+                    (d_bcrec[n].lo(1) == amrex::BCType::ext_dir) ||
+                    (d_bcrec[n].lo(1) == amrex::BCType::hoextrap);
+                bool extdir_or_ho_jhi =
+                    (d_bcrec[n].hi(1) == amrex::BCType::ext_dir) ||
+                    (d_bcrec[n].hi(1) == amrex::BCType::hoextrap);
+                amrex::Real qs;
+                if (j <= domain_jlo &&
+                    (d_bcrec[n].lo(1) == amrex::BCType::ext_dir)) {
                     qs = q(i, domain_jlo - 1, k, n);
                 } else if (
                     j >= domain_jhi + 1 &&
-                    (d_bcrec[n].hi(1) == BCType::ext_dir)) {
+                    (d_bcrec[n].hi(1) == amrex::BCType::ext_dir)) {
                     qs = q(i, domain_jhi + 1, k, n);
                 } else {
-                    Real qpls =
+                    amrex::Real qpls =
                         q(i, j, k, n) -
                         0.5 * amrex_calc_yslope_extdir(
                                   i, j, k, n, 2, q, extdir_or_ho_jlo,
                                   extdir_or_ho_jhi, domain_jlo, domain_jhi);
-                    Real qmns =
+                    amrex::Real qmns =
                         q(i, j - 1, k, n) +
                         0.5 * amrex_calc_yslope_extdir(
                                   i, j - 1, k, n, 2, q, extdir_or_ho_jlo,
@@ -167,11 +172,12 @@ void mol::compute_convective_fluxes(
             ybx, ncomp,
             [q, vmac,
              fy] AMREX_GPU_DEVICE(int i, int j, int k, int n) noexcept {
-                Real qpls =
+                amrex::Real qpls =
                     q(i, j, k, n) - 0.5 * amrex_calc_yslope(i, j, k, n, 2, q);
-                Real qmns = q(i, j - 1, k, n) +
-                            0.5 * amrex_calc_yslope(i, j - 1, k, n, 2, q);
-                Real qs;
+                amrex::Real qmns =
+                    q(i, j - 1, k, n) +
+                    0.5 * amrex_calc_yslope(i, j - 1, k, n, 2, q);
+                amrex::Real qs;
                 if (vmac(i, j, k) > small_vel) {
                     qs = qmns;
                 } else if (vmac(i, j, k) < -small_vel) {
@@ -184,7 +190,7 @@ void mol::compute_convective_fluxes(
     }
 
     extdir_lohi = amr_wind::utils::has_extdir_or_ho(
-        h_bcrec, ncomp, static_cast<int>(Direction::z));
+        h_bcrec, ncomp, static_cast<int>(amrex::Direction::z));
     has_extdir_lo = extdir_lohi.first;
     has_extdir_hi = extdir_lohi.second;
     if ((has_extdir_lo and domain_klo >= zbx.smallEnd(2) - 1) or
@@ -193,24 +199,27 @@ void mol::compute_convective_fluxes(
             zbx, ncomp,
             [d_bcrec, q, domain_klo, domain_khi, wmac,
              fz] AMREX_GPU_DEVICE(int i, int j, int k, int n) noexcept {
-                bool extdir_or_ho_klo = (d_bcrec[n].lo(2) == BCType::ext_dir) ||
-                                        (d_bcrec[n].lo(2) == BCType::hoextrap);
-                bool extdir_or_ho_khi = (d_bcrec[n].hi(2) == BCType::ext_dir) ||
-                                        (d_bcrec[n].hi(2) == BCType::hoextrap);
-                Real qs;
-                if (k <= domain_klo && (d_bcrec[n].lo(2) == BCType::ext_dir)) {
+                bool extdir_or_ho_klo =
+                    (d_bcrec[n].lo(2) == amrex::BCType::ext_dir) ||
+                    (d_bcrec[n].lo(2) == amrex::BCType::hoextrap);
+                bool extdir_or_ho_khi =
+                    (d_bcrec[n].hi(2) == amrex::BCType::ext_dir) ||
+                    (d_bcrec[n].hi(2) == amrex::BCType::hoextrap);
+                amrex::Real qs;
+                if (k <= domain_klo &&
+                    (d_bcrec[n].lo(2) == amrex::BCType::ext_dir)) {
                     qs = q(i, j, domain_klo - 1, n);
                 } else if (
                     k >= domain_khi + 1 &&
-                    (d_bcrec[n].hi(2) == BCType::ext_dir)) {
+                    (d_bcrec[n].hi(2) == amrex::BCType::ext_dir)) {
                     qs = q(i, j, domain_khi + 1, n);
                 } else {
-                    Real qpls =
+                    amrex::Real qpls =
                         q(i, j, k, n) -
                         0.5 * amrex_calc_zslope_extdir(
                                   i, j, k, n, 2, q, extdir_or_ho_klo,
                                   extdir_or_ho_khi, domain_klo, domain_khi);
-                    Real qmns =
+                    amrex::Real qmns =
                         q(i, j, k - 1, n) +
                         0.5 * amrex_calc_zslope_extdir(
                                   i, j, k - 1, n, 2, q, extdir_or_ho_klo,
@@ -230,11 +239,12 @@ void mol::compute_convective_fluxes(
             zbx, ncomp,
             [q, wmac,
              fz] AMREX_GPU_DEVICE(int i, int j, int k, int n) noexcept {
-                Real qpls =
+                amrex::Real qpls =
                     q(i, j, k, n) - 0.5 * amrex_calc_zslope(i, j, k, n, 2, q);
-                Real qmns = q(i, j, k - 1, n) +
-                            0.5 * amrex_calc_zslope(i, j, k - 1, n, 2, q);
-                Real qs;
+                amrex::Real qmns =
+                    q(i, j, k - 1, n) +
+                    0.5 * amrex_calc_zslope(i, j, k - 1, n, 2, q);
+                amrex::Real qs;
                 if (wmac(i, j, k) > small_vel) {
                     qs = qmns;
                 } else if (wmac(i, j, k) < -small_vel) {

amr-wind/core/Field.H

@@ -277,7 +277,8 @@ public:
      *  \param value Constant value for initialization
      *  \param start_comp Starting component index (0-based)
      *  \param num_comp Number of components from starting component to
-     * initialize \param num_ghost Number of ghost cells to include
+     * initialize
+     *  \param nghost Number of ghost cells to include
      */
     void setVal(
         amrex::Real value,

amr-wind/core/FieldFillPatchOps.H

@@ -173,10 +173,12 @@ class FieldFillPatchOps : public FieldFillPatchOpsBase
 public:
     using Functor = typename BCOpCreator::FunctorType;
     /**
-     *  @param field Field whose patches are filled by this instance
-     *  @param mesh  The mesh instance to determine amrex::Geometry at a level
-     *  @param time  Time instance
-     *  @param itype Interpolation type (default: conservative cell linear)
+     *  \param field Field whose patches are filled by this instance
+     *  \param mesh  The mesh instance to determine amrex::Geometry at a level
+     *  \param time  Time instance
+     *  \param itype Interpolation type (default: conservative cell linear)
+     *  \param face_itype Face interpolation type (default: face divergence
+     * free)
      */
     FieldFillPatchOps(
         Field& field,