[main] ccpp-physics SciDocs to github pages

.github/workflows/doxygen.yml

@@ -0,0 +1,136 @@
+name: Doxygen GitHub Pages Deploy Action
+
+on:
+  push:
+    branches:
+      - main
+      - scidocs_hsd_aqua
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+
+    - name: Install Doxygen + Graphviz + LaTeX
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y doxygen graphviz perl texlive-latex-base texlive-latex-extra texlive-fonts-recommended texlive-bibtex-extra
+
+    - name: Verify installations
+      run: |
+        which perl
+        which bibtex
+        doxygen --version
+
+    - name: Checkout current ccpp-physics code
+      uses: actions/checkout@v4
+      with:
+        path: ccpp_repo
+
+    - name: Checkout CCPP SCM main
+      uses: actions/checkout@v4
+      with:
+        repository: NCAR/ccpp-scm
+        path: scm_repo
+        fetch-depth: 0
+        submodules: recursive
+
+    - name: Switch physics submodule to main
+      run: |
+        cd scm_repo/ccpp/physics
+        git remote set-url origin https://github.com/hertneky/ccpp-physics.git
+        git fetch origin
+        git checkout scidocs_hsd_aqua
+
+    - name: Generate metadata tables main branch
+      run: |
+        cd scm_repo
+        mkdir -p ccpp/physics/physics/docs/doc/html
+        export PYTHONPATH=$GITHUB_WORKSPACE/scm_repo/ccpp/framework/scripts:$GITHUB_WORKSPACE/scm_repo/ccpp/framework/scripts/parse_tools
+        ./ccpp/framework/scripts/metadata2html.py -c ccpp/config/ccpp_prebuild_config.py
+        mv ccpp/physics/physics/docs/*.html ccpp/physics/physics/docs/doc/html
+
+    - name: Build HSD docs
+      run: |
+        cd scm_repo/ccpp/physics/physics/docs
+        doxygen ccpphsd_doxyfile
+        mkdir -p $GITHUB_WORKSPACE/physics/docs/html/HSD
+        mv doc/html/* $GITHUB_WORKSPACE/physics/docs/html/HSD
+
+    - name: Switch to v7 tag
+      run: |
+        cd scm_repo
+        git fetch origin tag v7.0.0
+        git checkout v7.0.0
+        git submodule update --init --recursive
+
+    - name: Generate metadata tables v7 branch
+      run: |
+        cd scm_repo
+        mkdir -p ccpp/physics/physics/docs/doc/html
+        export PYTHONPATH=$GITHUB_WORKSPACE/scm_repo/ccpp/framework/scripts:$GITHUB_WORKSPACE/scm_repo/ccpp/framework/scripts/parse_tools
+        ./ccpp/framework/scripts/metadata2html.py -c ccpp/config/ccpp_prebuild_config.py
+        mv ccpp/physics/physics/docs/*.html ccpp/physics/physics/docs/doc/html
+
+    - name: Build v7 docs
+      run: |
+        cd scm_repo/ccpp/physics/physics/docs
+        doxygen ccpp_doxyfile
+        mkdir -p $GITHUB_WORKSPACE/physics/docs/html/V7
+        mv doc/html/* $GITHUB_WORKSPACE/physics/docs/html/V7
+
+    - name: Switch physics submodule to SRWv3 (ufs-community)
+      run: |
+        cd scm_repo/ccpp/physics
+        git remote set-url origin https://github.com/ufs-community/ccpp-physics.git
+        git fetch origin release/srw-v3
+        git checkout -B release/srw-v3 FETCH_HEAD
+
+    - name: Generate metadata tables SRWv3 branch
+      run: |
+        cd scm_repo
+        mkdir -p ccpp/physics/physics/docs/doc/html
+        export PYTHONPATH=$GITHUB_WORKSPACE/scm_repo/ccpp/framework/scripts:$GITHUB_WORKSPACE/scm_repo/ccpp/framework/scripts/parse_tools
+        ./ccpp/framework/scripts/metadata2html.py -c $GITHUB_WORKSPACE/ccpp_repo/physics/docs/pdftxt/RE300/ccpp_prebuild_config.py
+        mv ccpp/physics/physics/docs/*.html ccpp/physics/physics/docs/doc/html
+
+    - name: Build SRWv3 docs
+      run: |
+        cd scm_repo/ccpp/physics/physics/docs
+        doxygen ccppsrw_doxyfile
+        mkdir -p $GITHUB_WORKSPACE/physics/docs/html/SRWv3
+        mv doc/html/* $GITHUB_WORKSPACE/physics/docs/html/SRWv3
+
+    - name: Switch to submodule main (ncar)
+      run: |
+        cd scm_repo/ccpp/physics
+        git remote set-url origin https://github.com/hertneky/ccpp-physics.git
+        git fetch origin scidocs_hsd_aqua
+        git checkout -B scidocs_hsd_aqua FETCH_HEAD
+
+    - name: Build landing page
+      run: |
+        cd scm_repo/ccpp/physics/physics/docs
+        doxygen mainpage_doxyfile
+        mv html/main/* $GITHUB_WORKSPACE/physics/docs/html
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v5
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: physics/docs/html
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4.0.5

physics/docs/_doxygen/custom.css

@@ -55,3 +55,8 @@ html.dark-mode .bordered_image object[type="image/svg+xml"] /* doxygen 1.9.3 */
 .title_screenshot .caption {
     display: none;
 }
+
+#back-to-landing {
+  padding: 10px 20px;
+  font-size: 14px;
+}

physics/docs/_doxygen/header.html

@@ -41,6 +41,20 @@
 </head>
 <body>
 
+<div id="back-to-landing">
+  <a href="/ccpp-physics/">← Back to Documentation Home</a>
+</div>
+
+<script>
+  if (window.location.pathname.endsWith('/ccpp-physics/') ||
+      window.location.pathname.endsWith('/ccpp-physics/index.html')) {
+    document.addEventListener("DOMContentLoaded", function() {
+      var el = document.getElementById("back-to-landing");
+      if (el) el.style.display = "none";
+    });
+  }
+</script>
+
 <!-- https://tholman.com/github-corners/ -->
 <a href="https://github.com/ufs-community/ccpp-physics" class="github-corner" title="View source on GitHub" target="_blank" rel="noopener noreferrer">
     <svg viewBox="0 0 250 250" width="60" height="60" style="position: absolute; top: 0; border: 0; right: 0; z-index: 99;" aria-hidden="true">

physics/docs/ccpp_doxyfile

@@ -74,7 +74,7 @@ PROJECT_ICON           =
 # entered, it will be relative to the location where Doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc
+OUTPUT_DIRECTORY       = html
 
 # If the CREATE_SUBDIRS tag is set to YES then Doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -840,7 +840,7 @@ CITE_BIB_FILES         = library.bib
 # launching external tools will then become
 # PATH=/Library/TeX/texbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
 
-EXTERNAL_TOOL_PATH     =
+EXTERNAL_TOOL_PATH     = /usr/bin
 
 #---------------------------------------------------------------------------
 # Configuration options related to warning and progress messages
@@ -1127,7 +1127,7 @@ EXCLUDE_SYMBOLS        =
 # command).
 
 EXAMPLE_PATH           = pdftxt/RE7 \
-                         doc/html
+                         pdftxt
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -1173,7 +1173,7 @@ IMAGE_PATH             = img
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by Doxygen.
 
-INPUT_FILTER           =
+INPUT_FILTER           = 
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the
@@ -1186,7 +1186,7 @@ INPUT_FILTER           =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by Doxygen.
 
-FILTER_PATTERNS        =
+FILTER_PATTERNS        = 
 
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
 # INPUT_FILTER) will also be used to filter the input files that are used for
@@ -1341,7 +1341,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = html
+HTML_OUTPUT            = V7
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).
@@ -2809,7 +2809,7 @@ INTERACTIVE_SVG        = YES
 # found. If left blank, it is assumed the dot tool can be found in the path.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_PATH               = /opt/homebrew/bin
+DOT_PATH               =
 
 # The DOTFILE_DIRS tag can be used to specify one or more directories that
 # contain dot files that are included in the documentation (see the \dotfile

physics/docs/ccpphsd_doxyfile

@@ -42,7 +42,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "CCPP SciDoc for Idealized Regional TC Capability"
+PROJECT_NAME           = "CCPP SciDoc for HSD Capabilities"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -984,20 +984,27 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = pdftxt/HAFS_TC_suite.txt  \
+INPUT                  = pdftxt/HSD_overview.txt \
+                         pdftxt/Idealized_TC.txt \
+                         pdftxt/Aquaplanet.txt \
+                         pdftxt/HAFS_TC_suite.txt  \
+                         pdftxt/GFS_v17_p8_ugwpv1_aquaplanet_suite.txt \
+                         pdftxt/suite_input.nml.txt \
+                         pdftxt/acronyms.txt   \
                          pdftxt/GFS_RRTMG.txt \
                          pdftxt/GFS_SFCLYR.txt \
+                         pdftxt/GFS_NSST.txt \
                          pdftxt/GFS_OCEAN.txt \
                          pdftxt/NOAH_LSM.txt \
+                         pdftxt/NOAHMP_LSM.txt \
                          pdftxt/GFS_SFCSICE.txt \
                          pdftxt/GFS_SATMEDMFVDIFQ.txt \
                          pdftxt/UGWPv0.txt \
+                         pdftxt/GFS_OZPHYS.txt \
                          pdftxt/GFS_H2OPHYS.txt \
                          pdftxt/GFS_SAMFdeep.txt \
                          pdftxt/GFS_SAMFshal.txt \
                          pdftxt/THOMPSON.txt \
-                         pdftxt/suite_input.nml.txt \
-                         pdftxt/acronyms.txt   \ 
                          ../MP \
                          ../CONV \
                          ../GWD \
@@ -1134,7 +1141,8 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = pdftxt/RE300 \
+EXAMPLE_PATH           = pdftxt/HSD \
+                         pdftxt \
                          doc/html
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
@@ -1428,7 +1436,8 @@ HTML_STYLESHEET        =
 HTML_EXTRA_STYLESHEET  = _doxygen/doxygen-awesome.css \
                          _doxygen/doxygen-awesome-sidebar-only.css \
                          _doxygen/doxygen-awesome-sidebar-only-darkmode-toggle.css \
-                         _doxygen/doxygen-awesome-ccpp.css
+                         _doxygen/doxygen-awesome-ccpp.css \
+                         _doxygen/custom.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note

physics/docs/ccppsrw_doxyfile

@@ -1450,7 +1450,8 @@ HTML_STYLESHEET        =
 HTML_EXTRA_STYLESHEET  = _doxygen/doxygen-awesome.css \
                          _doxygen/doxygen-awesome-sidebar-only.css \
                          _doxygen/doxygen-awesome-sidebar-only-darkmode-toggle.css \
-                         _doxygen/doxygen-awesome-ccpp.css
+                         _doxygen/doxygen-awesome-ccpp.css \
+                         _doxygen/custom.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note

physics/docs/mainpage.md

@@ -0,0 +1,30 @@
+# CCPP Physics Scientific Documentation
+
+The Common Community Physics Package (CCPP) provides scientific documentation for the physics suites and parameterizations used across a variety of atmospheric modeling applications. The documentation describes the scientific basis, configuration options, and implementation details for the parameterizations included in the CCPP physics suites for different modeling systems and use cases.
+
+- [CCPP Physics V7.0.0 Scientific Documentation](./V7/)
+- [CCPP Physics UFS Hierarchical System Development (HSD) Scientific Documentation](./HSD/)
+- [CCPP Physics SRW v3.0.0 Scientific Documentation](./SRWv3/)
+
+For more information about the CCPP including Release Information, Technical Documentation, and Code, please visit the 
+<a href="https://dtcenter.org/community-code/common-community-physics-package-ccpp" target="_blank">CCPP website</a>, hosted by the Developmental Testbed Center (DTC).
+
+## Acknowledgements
+
+CCPP team would like to express our deepest gratitude for UFS physics developers' contribution to the
+development of CCPP-Physics.
+\n We would also like to give special thanks to:
+
+- \b NOAA \b NWS \b Environmental \b Modeling \b Center
+- \b NOAA \b OAR \b Global \b Systems \b Laboratory
+- \b NOAA \b OAR \b Physical \b Sciences \b Laboratory
+- \b NOAA \b OAR \b National \b Severe \b Storms \b Laboratory
+- \b NOAA \b OAR \b Atlantic \b Oceanographic \b & \b Meteorological \b Laboratory
+- \b Atmospheric \b and \b Environmental \b Research, \b Inc.
+- \b Joint \b Center \b for \b Satellite \b Data \b Assimilation
+- \b NASA \b Goddard \b Space \b Flight \b Center
+- \b U.S. \b Naval \b Research \b Laboratory
+- \b NOAA \b OAR \b Geophysical \b Fluid \b Dynamics \b Laboratory
+
+for their support and contribution for this CCPP scientific documentation (SciDoc).
+\n Thanks also to the CCPP SciDoc Team at the Developmental Testbed Center: Man Zhang, Ligia Bernardet, Mike Kavulich, and Tracy Hertneky.