Merge pull request NOAA-EMC#187 from NOAA-EMC/ejh_docs

added documentation build

.github/workflows/developer.yml

@@ -22,17 +22,21 @@ jobs:
       FC: gfortran
       CC: gcc
 
+    permissions:
+      id-token: write
+      pages: write
+
     steps:
 
     - name: install
       run: |
         sudo apt-get update
         sudo apt-get install libnetcdf-dev libnetcdff-dev netcdf-bin pkg-config
-        sudo apt-get install libpng-dev autotools-dev libaec-dev autoconf gcovr
+        sudo apt-get install libpng-dev autotools-dev libaec-dev autoconf gcovr doxygen
 
     - name: cache-jasper
       id: cache-jasper
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: ~/jasper
         key: jasper-${{ runner.os }}-1.900.1
@@ -129,6 +133,9 @@ jobs:
         path: ~/data
         key: data-2
 
+    - name: Setup Pages
+      uses: actions/configure-pages@v4
+
     - name: build
       run: |
         cd wgrib2
@@ -137,7 +144,7 @@ jobs:
         export CFLAGS='-Wall -g -fprofile-abs-path -fprofile-arcs -ftest-coverage -O0'        
         export FCFLAGS='-Wall -g -fprofile-abs-path -fprofile-arcs -ftest-coverage -O0'        
         export FFLAGS='-Wall -g -fprofile-abs-path -fprofile-arcs -ftest-coverage -O0'        
-        cmake .. -DFTP_TEST_FILES=ON -DCMAKE_PREFIX_PATH="~/ip;~/ip2;~/sp" -DTEST_FILE_DIR=/home/runner/data -DUSE_NETCDF4=ON -DUSE_AEC=ON -DUSE_IPOLATES=ON
+        cmake .. -DENABLE_DOCS=ON -DFTP_TEST_FILES=ON -DCMAKE_PREFIX_PATH="~/ip;~/ip2;~/sp" -DTEST_FILE_DIR=/home/runner/data -DUSE_NETCDF4=ON -DUSE_AEC=ON -DUSE_IPOLATES=ON
         make VERBOSE=1
         ctest --verbose --output-on-failure --rerun-failed
         gcovr --root .. -v  --html-details --exclude ../tests --exclude CMakeFiles --print-summary -o test-coverage.html &> /dev/null
@@ -155,3 +162,12 @@ jobs:
         path: |
           wgrib2/build/*.html
           wgrib2/build/*.css
+
+    - name: Upload built documentation
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: wgrib2/build/docs/html  # Path to the built site files
+
+    - name: Deploy
+      uses: actions/deploy-pages@v1
+

CMakeLists.txt

@@ -10,6 +10,7 @@ file(STRINGS "VERSION" pVersion)
 project(wgrib2 VERSION ${pVersion} LANGUAGES Fortran C)
 
 # Handle user build options.
+option(ENABLE_DOCS "Enable generation of doxygen-based documentation." OFF)
 option(USE_NETCDF3 "Use NetCDF-3?" off)
 option(USE_NETCDF4 "Use NetCDF-4?" off)
 option(USE_HDF5 "Use HDF5?" off)
@@ -183,3 +184,10 @@ include(CTest)
 if(BUILD_TESTING)
   add_subdirectory(tests)
 endif()
+
+# Determine whether or not to generate documentation.
+if(ENABLE_DOCS)
+  find_package(Doxygen REQUIRED)
+  add_subdirectory(docs)  
+endif()
+

README.md

@@ -6,12 +6,15 @@ manipulating grib2 files, with a CMake build.
 See wgrib2 documentation
 [here](https://www.cpc.ncep.noaa.gov/products/wesley/wgrib2/).
 
+See also the [develop branch doxygen
+build](https://noaa-emc.github.io/wgrib2).
+
 This release of the wgrib2 package, with CMake build capability, is
 part of the [NCEPLIBS](https://github.com/NOAA-EMC/NCEPLIBS) project.
 
 # Users
 
-Wgrib2 is used by the following NOAA projects:
+Wgrib2 is used by the following projects:
 * [NOMADS](nomads.ncep.noaa.gov) uses wgrib2 in grib_filter (a wrapper for
    wgrib2) wgrib2 is used to create the *.idx files for random access.
 * [global-workflow](https://github.com/NOAA-EMC/global-workflow/),
@@ -34,20 +37,17 @@ Wgrib2 is used by the following NOAA projects:
   post-processing of the atmosphere component has been using wgrib2 to
   interplate the UPP output master files in Gaussian grid into
   pgrb2/pgrb2b files in lat-lon grid.
-* (pywgrib2_s)[https://www.cpc.ncep.noaa.gov/products/wesley/wgrib2/pywgrib2_s.html]
+* Wgrib2 is the suggested regridding tool for GRIB2 by
+  [UPP](https://github.com/NOAA-EMC/UPP).
+* [pywgrib2_s](https://www.cpc.ncep.noaa.gov/products/wesley/wgrib2/pywgrib2_s.html)
   and pywgrib2_xy call wgrib2.
-
-Wgrib2 is used in the following projects outside NOAA:
-
-* (RNomads)[https://cran.r-project.org/web/packages/rNOMADS/rNOMADS.pdf]
-is an R module that can get grib files from nomads.ncep.noaa.gov and
-read them. RNomads will run in windows and linux, and the code uses
-wgrib2.
+* [RNomads](https://cran.r-project.org/web/packages/rNOMADS/rNOMADS.pdf)
+  is an R module that can get grib files from nomads.ncep.noaa.gov and
+  read them. RNomads will run in windows and linux, and the code uses
+  wgrib2.
 * wgrib2 is included in anaconda, redhat and other repositories.
-* (GrADS)[http://cola.gmu.edu/grads/] uses wgrib2 to create control
-files. Also used to create ctl files for the grads dods server.
-* Wgrib2 is the suggested regridding tool for grib2 by
-(UPP)[https://github.com/NOAA-EMC/UPP].
+* [GrADS](http://cola.gmu.edu/grads/) uses wgrib2 to create control
+  files. Also used to create ctl files for the grads dods server.
 
 ### Authors
 

docs/CMakeLists.txt

@@ -0,0 +1,17 @@
+# This is the CMake file for building the docs directory of wgrib2.
+#
+# Ed Hartnett 7/17/24
+
+IF(ENABLE_DOCS)
+
+  # Create doxyfile.
+  SET(abs_top_srcdir "${CMAKE_SOURCE_DIR}")
+  SET(abs_top_builddir "${CMAKE_BINARY_DIR}")
+  CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+  ADD_CUSTOM_TARGET(doc ALL
+    ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Generating API Documentation with Doxygen" VERBATIM)
+
+ENDIF(ENABLE_DOCS)
+