From c0a9b667f57d445b1732ef3f8153a8ee01911d04 Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Wed, 24 Jul 2024 15:18:28 -0700 Subject: [PATCH 1/9] CMakeLists.txt: add enable doxygen support --- CMakeLists.txt | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index b485488b3..db4495605 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -13,7 +13,7 @@ project( get_directory_property(hasParent PARENT_DIRECTORY) if(hasParent) - # Unset flags that come from Parent (ie UFS or other coupled build) + # Unset flags that come from Parent (ie UFS or other coupled build) # for potential (-r8/-r4) conflict set(CMAKE_Fortran_FLAGS "") set(CMAKE_C_FLAGS "") @@ -22,8 +22,9 @@ endif() set(MULTI_ESMF OFF CACHE BOOL "Build ww3_multi_esmf library") set(NETCDF ON CACHE BOOL "Build NetCDF programs (requires NetCDF)") -set(ENDIAN "BIG" CACHE STRING "Endianness of unformatted output files. Valid values are 'BIG', 'LITTLE', 'NATIVE'.") +set(ENDIAN "BIG" CACHE STRING "Endianness of unformatted output files. Valid values are 'BIG', 'LITTLE', 'NATIVE'.") set(EXCLUDE_FIND "" CACHE STRING "Don't try and search for these libraries (assumd to be handled by the compiler/wrapper)") +set(ENABLE_DOCS OFF CACHE BOOL "Enable building of doxygen generated documentation") # make sure all "exclude_find" entries are lower case list(TRANSFORM EXCLUDE_FIND TOLOWER) @@ -59,6 +60,13 @@ endif() add_subdirectory(model) +# Turn on doxygen html documentation +if (ENABLE_DOCS) + list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/docs/cmake") + include(EnableDoxygen) + add_subdirectory(docs) +endif() + # Turn on unit testing. #include(CTest) #if(BUILD_TESTING) From dd87585aaba51b754162e9fcfaaa52d5bd113242 Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Wed, 24 Jul 2024 15:20:39 -0700 Subject: [PATCH 2/9] Doxyfile.in: add templated src/bin dirs --- docs/Doxyfile.in | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 23349c8da..7f407c790 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = docs +OUTPUT_DIRECTORY = @bin_basedir@/docs # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -829,7 +829,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = model/src +INPUT = @src_basedir@/model/src # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -2285,7 +2285,7 @@ CLASS_DIAGRAMS = NO # DIA_PATH tag allows you to specify the directory where the dia binary resides. # If left empty dia is assumed to be found in the default search path. -DIA_PATH = +DIA_PATH = # If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. From 724c2964e6aabdc08b5ae30166a1cfb66f868c52 Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Wed, 24 Jul 2024 15:23:18 -0700 Subject: [PATCH 3/9] docs/CMakeLists.txt: module call EnableDoxygen() --- docs/CMakeLists.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/CMakeLists.txt diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 000000000..7aa89edeb --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1 @@ +EnableDoxygen(docs) From 755b79935b1292c4f4f2aa261c8e0084587197d4 Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Wed, 24 Jul 2024 15:34:11 -0700 Subject: [PATCH 4/9] add docs/cmake/EnableDoxygen.cmake --- docs/cmake/EnableDoxygen.cmake | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/cmake/EnableDoxygen.cmake diff --git a/docs/cmake/EnableDoxygen.cmake b/docs/cmake/EnableDoxygen.cmake new file mode 100644 index 000000000..0c9293bc2 --- /dev/null +++ b/docs/cmake/EnableDoxygen.cmake @@ -0,0 +1,27 @@ +# doxygen documentation- Matt Masarik 24-Jul-2024. +function(EnableDoxygen outdir) + find_package(Doxygen) + if (NOT DOXYGEN_FOUND) + add_custom_target(enable_docs + COMMAND false + COMMENT "Doxygen not found") + return() + endif() + + set(src_basedir "${CMAKE_SOURCE_DIR}") + set(bin_basedir "${CMAKE_BINARY_DIR}") + file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/${outdir}/html) + CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/docs/Doxyfile.in + ${CMAKE_BINARY_DIR}/${outdir}/Doxyfile @ONLY) + set(DOXYGEN_GENERATE_HTML YES) + set(DOXYGEN_QUIET YES) +###MTM set(DOXYGEN_HTML_OUTPUT ${CMAKE_BINARY_DIR}/${outdir}/html) + add_custom_target(enable_docs + COMMAND + ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/${outdir}/Doxyfile +###MTM ALL + WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/${outdir} + COMMENT "Generate Doxygen HTML documentation") + message("-- Doxygen HTML index page: " + ${CMAKE_BINARY_DIR}/${outdir}/html/index.html) +endfunction() From 63ffd974bb3d84d8be6c9709cefa12ee6595412f Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Wed, 24 Jul 2024 15:39:43 -0700 Subject: [PATCH 5/9] EnableDoxygen.cmake - clean up --- docs/cmake/EnableDoxygen.cmake | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/cmake/EnableDoxygen.cmake b/docs/cmake/EnableDoxygen.cmake index 0c9293bc2..6b19434b5 100644 --- a/docs/cmake/EnableDoxygen.cmake +++ b/docs/cmake/EnableDoxygen.cmake @@ -15,13 +15,13 @@ function(EnableDoxygen outdir) ${CMAKE_BINARY_DIR}/${outdir}/Doxyfile @ONLY) set(DOXYGEN_GENERATE_HTML YES) set(DOXYGEN_QUIET YES) -###MTM set(DOXYGEN_HTML_OUTPUT ${CMAKE_BINARY_DIR}/${outdir}/html) add_custom_target(enable_docs COMMAND - ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/${outdir}/Doxyfile -###MTM ALL - WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/${outdir} - COMMENT "Generate Doxygen HTML documentation") + ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/${outdir}/Doxyfile + WORKING_DIRECTORY + ${CMAKE_BINARY_DIR}/${outdir} + COMMENT + "Generate Doxygen HTML documentation") message("-- Doxygen HTML index page: " ${CMAKE_BINARY_DIR}/${outdir}/html/index.html) endfunction() From 8c6f2b35665527effe53356d47f0884f56d03a40 Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Tue, 30 Jul 2024 12:48:05 -0700 Subject: [PATCH 6/9] remove 'html' --- CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index db4495605..5070e3aa5 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -60,7 +60,7 @@ endif() add_subdirectory(model) -# Turn on doxygen html documentation +# Turn on doxygen documentation if (ENABLE_DOCS) list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/docs/cmake") include(EnableDoxygen) From 2652f867163206e40c1f7e04f099e1b1498d9c19 Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Tue, 30 Jul 2024 12:49:11 -0700 Subject: [PATCH 7/9] Doxygen --- docs/cmake/EnableDoxygen.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cmake/EnableDoxygen.cmake b/docs/cmake/EnableDoxygen.cmake index 6b19434b5..02246f9e5 100644 --- a/docs/cmake/EnableDoxygen.cmake +++ b/docs/cmake/EnableDoxygen.cmake @@ -1,4 +1,4 @@ -# doxygen documentation- Matt Masarik 24-Jul-2024. +# Doxygen documentation- Matt Masarik 24-Jul-2024. function(EnableDoxygen outdir) find_package(Doxygen) if (NOT DOXYGEN_FOUND) From 8f33a59589e6e4bb307ef5e0ba5d7a8a19104f1e Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Tue, 30 Jul 2024 13:09:26 -0700 Subject: [PATCH 8/9] update src/dest dirs --- docs/Doxyfile.in | 4 ++-- docs/cmake/EnableDoxygen.cmake | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 7f407c790..93a26c5a2 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = @bin_basedir@/docs +OUTPUT_DIRECTORY = @doc_output@ # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -829,7 +829,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = @src_basedir@/model/src +INPUT = @src_input@ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/docs/cmake/EnableDoxygen.cmake b/docs/cmake/EnableDoxygen.cmake index 02246f9e5..c413a1036 100644 --- a/docs/cmake/EnableDoxygen.cmake +++ b/docs/cmake/EnableDoxygen.cmake @@ -8,8 +8,8 @@ function(EnableDoxygen outdir) return() endif() - set(src_basedir "${CMAKE_SOURCE_DIR}") - set(bin_basedir "${CMAKE_BINARY_DIR}") + set(src_input "${CMAKE_SOURCE_DIR}/model/src") + set(doc_output "${CMAKE_BINARY_DIR}/${outdir}") file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/${outdir}/html) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/docs/Doxyfile.in ${CMAKE_BINARY_DIR}/${outdir}/Doxyfile @ONLY) From a38d9eb76c131505a75f6886b6b1b64271b1e9db Mon Sep 17 00:00:00 2001 From: Matt Masarik Date: Wed, 31 Jul 2024 10:51:29 -0700 Subject: [PATCH 9/9] EnableDoxygen: make Doxygen package required --- docs/cmake/EnableDoxygen.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cmake/EnableDoxygen.cmake b/docs/cmake/EnableDoxygen.cmake index c413a1036..20af91e59 100644 --- a/docs/cmake/EnableDoxygen.cmake +++ b/docs/cmake/EnableDoxygen.cmake @@ -1,6 +1,6 @@ # Doxygen documentation- Matt Masarik 24-Jul-2024. function(EnableDoxygen outdir) - find_package(Doxygen) + find_package(Doxygen REQUIRED) if (NOT DOXYGEN_FOUND) add_custom_target(enable_docs COMMAND false