Merge pull request #2335 from bilke/doxygen

Refactored Doxygen setup

CMakeLists.txt

@@ -3,7 +3,7 @@
 #####################
 
 # Specify minimum CMake version
-cmake_minimum_required(VERSION 3.8)
+cmake_minimum_required(VERSION 3.9)
 
 # Set CMake policies
 cmake_policy(SET CMP0011 NEW)
@@ -349,3 +349,6 @@ check_header_compilation()
 
 include(scripts/cmake/MarkVariablesAdvanced.cmake)
 unset(PRE_INSTALL_RUN CACHE)
+
+include(FeatureSummary)
+feature_summary(WHAT ALL)

NumLib/ODESolver/NonlinearSolver.h

@@ -88,7 +88,8 @@ public:
      * \param linear_solver the linear solver used by this nonlinear solver.
      * \param maxiter the maximum number of iterations used to solve the
      *                equation.
-     * \param damping \copydoc _damping
+     * \param damping A positive damping factor.
+     * \see _damping
      */
     explicit NonlinearSolver(GlobalLinearSolver& linear_solver,
                              int const maxiter,

SimpleTests/MeshTests/MPI/CMakeLists.txt

@@ -13,7 +13,7 @@ if(OGS_USE_PETSC)
 endif()
 
 if(OGS_USE_MPI)
-    target_link_libraries(test_node_partitioned_mesh ${MPI_CXX_LIBRARIES})
+    target_link_libraries(test_node_partitioned_mesh MPI::MPI_CXX)
 endif()
 
 AddTest(

Tests/CMakeLists.txt

@@ -58,7 +58,7 @@ if(OGS_USE_PETSC)
 endif()
 
 if(OGS_USE_MPI)
-    target_link_libraries(testrunner ${MPI_CXX_LIBRARIES})
+    target_link_libraries(testrunner MPI::MPI_CXX)
 endif()
 
 if(OGS_BUILD_SWMM)

cmake-modules @ 819ad94e

-Subproject commit f4b0a053e53de2f4fc75a36af1dd0eede236fc68
+Subproject commit 819ad94ebd33c80da2772dc82319f77cc14bf175

scripts/cmake/DocumentationSetup.cmake

-if(DOXYGEN_FOUND)
-
-    option(DOCS_GENERATE_DOCSET "Generate Dash Docsets." OFF)
-
-    set(DOT_FOUND "NO")
-    if(DOXYGEN_DOT_FOUND)
-        set(DOT_FOUND "YES")
-    endif()
-
-    add_custom_target(doc ${DOXYGEN_EXECUTABLE} ${PROJECT_BINARY_DIR}/Doxyfile
-        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
-        COMMENT "Generating source code documentation with Doxygen." VERBATIM)
-
-    # Defaults
-    set(DOCS_GENERATE_TREEVIEW_STRING "YES" CACHE INTERNAL "")
-    set(DOCS_DISABLE_INDEX_STRING "NO" CACHE INTERNAL "")
-    set(DOCS_GENERATE_DOCSET_STRING "NO" CACHE INTERNAL "")
-    set(DOCS_SEARCHENGINE_STRING "YES" CACHE INTERNAL "")
+if(NOT DOXYGEN_FOUND)
+    return()
+endif()
 
-    # Dash Docsets
-    if(DOCS_GENERATE_DOCSET)
-        find_program(DOCSETUTIL_TOOLPATH docsetutil
-            PATH /Applications/Xcode.app/Contents/Developer/usr/bin)
-        if(NOT DOCSETUTIL_TOOLPATH)
-            message(FATAL_ERROR "docsetutil required for Docset-generation!")
-        endif()
-        set(DOCS_GENERATE_TREEVIEW_STRING "NO" CACHE INTERNAL "")
-        set(DOCS_DISABLE_INDEX_STRING "YES" CACHE INTERNAL "")
-        set(DOCS_GENERATE_DOCSET_STRING "YES" CACHE INTERNAL "")
-        set(DOCS_SEARCHENGINE_STRING "NO" CACHE INTERNAL "")
-        add_custom_command(TARGET doc POST_BUILD
-            COMMAND make
-            COMMAND mv org.doxygen.Project.docset ogs6.docset
-            WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/docs
-            COMMENT "Generating docset ...")
-        configure_file(Documentation/DocsetFeed.xml.in ${PROJECT_BINARY_DIR}/docs/ogs6.xml)
-    endif()
+# Fix for https://github.com/doxygen/doxygen/issues/6725
+set(DOXYGEN_LATEX_MAKEINDEX_CMD "makeindex")
 
-    if(IS_CI)
-        set(OGS_DOXYGEN_LOGFILE "${PROJECT_BINARY_DIR}/DoxygenWarnings.log" CACHE INTERNAL "")
-    endif()
+set(DOXYGEN_EXCLUDE
+    ${PROJECT_SOURCE_DIR}/ThirdParty
+    ${PROJECT_SOURCE_DIR}/scripts
+    ${PROJECT_SOURCE_DIR}/Tests
+    ${PROJECT_SOURCE_DIR}/Documentation/ProjectFile
+    ${PROJECT_SOURCE_DIR}/web)
+set(DOXYGEN_FILE_PATTERNS *.h *.cpp *.tpp *.dox)
+set(DOXYGEN_PROJECT_NAME "OGS ${OGS_VERSION}")
+set(DOXYGEN_PROJECT_VERSION ${GIT_SHA1_SHORT})
+set(DOXYGEN_PROJECT_LOGO ${PROJECT_SOURCE_DIR}/Documentation/OpenGeoSys-Logo.png)
+set(DOXYGEN_HTML_OUTPUT ${PROJECT_BINARY_DIR}/docs)
+set(DOXYGEN_EXTRACT_ALL YES)
+set(DOXYGEN_EXTRACT_PRIVATE YES)
+set(DOXYGEN_EXTRACT_PACKAGE YES)
+set(DOXYGEN_EXTRACT_STATIC YES)
+set(DOXYGEN_EXTRACT_ANON_NSPACES YES)
+set(DOXYGEN_SORT_BY_SCOPE_NAME YES)
+set(DOXYGEN_LAYOUT_FILE ${PROJECT_SOURCE_DIR}/Documentation/DoxygenLayout.xml)
+set(DOXYGEN_CITE_BIB_FILES ${PROJECT_SOURCE_DIR}/Documentation/bibliography)
+set(DOXYGEN_WARN_LOGFILE ${PROJECT_BINARY_DIR}/DoxygenWarnings.log)
+set(DOXYGEN_EXCLUDE_PATTERNS moc_* ui_* CMake*)
+set(DOXYGEN_IMAGE_PATH ${PROJECT_SOURCE_DIR}/Documentation/images)
+set(DOXYGEN_SOURCE_BROWSER YES)
+set(DOXYGEN_INLINE_SOURCES YES)
+set(DOXYGEN_REFERENCED_BY_RELATION YES)
+set(DOXYGEN_REFERENCES_RELATION YES)
+set(DOXYGEN_GENERATE_TREEVIEW YES)
+set(DOXYGEN_USE_MATHAX YES)
+set(DOXYGEN_MATHAX_RELPATH https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1)
+set(DOXYGEN_GENERATE_LATEX NO)
+set(DOXYGEN_PREDEFINED DOXYGEN_DOCU_ONLY)
+set(DOXYGEN_ALIASES
+    "per{1} = \\1<sup>-1</sup>"
+    "ogs_file_param{1} = \\xrefitem ogs_file_param \\\"Input File Parameter\\\" \\\"List of all Input File Parameters\\\" \\ref ogs_file_param__\\1 \\\"\\1\\\""
+    "ogs_file_attr{1} = \\xrefitem ogs_file_param \\\"Input File Parameter\\\" \\\"List of all Input File Parameters\\\" \\ref ogs_file_attr__\\1 \\\"\\1\\\""
+    "ogs_file_special = \\xrefitem ogs_file_param \\\"Input File Parameter\\\" \\\"List of all Input File Parameters\\\" special OGS input file parameter"
+    "ogs_file_param_special{1} = \\xrefitem ogs_file_param \\\"Input File Parameter\\\" \\\"List of all Input File Parameters\\\" \\ref ogs_file_param__\\1 \\\"\\1\\\""
+    "ogs_file_attr_special{1} = \\xrefitem ogs_file_param \\\"Input File Parameter\\\" \\\"List of all Input File Parameters\\\" \\ref ogs_file_attr__\\1 \\\"\\1\\\""
+    "ogs_missing_documentation = \\xrefitem ogs_missing_documentation \\\"Missing Documentation\\\" \\\"OGS Input File Parameters&mdash\;List of incomplete documentation pages\\\" Documentation missing/incomplete")
 
-    configure_file(Documentation/Doxyfile.in ${PROJECT_BINARY_DIR}/Doxyfile)
+doxygen_add_docs(doc
+    ${PROJECT_SOURCE_DIR}/
+    ${PROJECT_BINARY_DIR}/DocAux/dox)
 
-    if (BASH_TOOL_PATH AND PYTHON_EXECUTABLE)
-        set(doc_use_external_tools TRUE)
-    else()
-        set(doc_use_external_tools FALSE)
-    endif()
+if (BASH_TOOL_PATH AND PYTHON_EXECUTABLE)
+    set(doc_use_external_tools TRUE)
+else()
+    set(doc_use_external_tools FALSE)
+endif()
+# TODO that will always transform all of the input files no matter if they changed
+# maybe this behaviour can be changed to on-demand processing
+add_custom_target(internal_pre_doc
+    ${CMAKE_COMMAND}
+    -DPROJECT_BINARY_DIR=${PROJECT_BINARY_DIR}
+    -DPROJECT_SOURCE_DIR=${PROJECT_SOURCE_DIR}
+    -Ddoc_use_external_tools=${doc_use_external_tools}
+    -P ${PROJECT_SOURCE_DIR}/scripts/cmake/DocumentationProjectFile.cmake
+    WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+    COMMENT "Generating project file documentation hierarchy." VERBATIM)
+add_dependencies(doc internal_pre_doc)
 
-    # TODO that will always transform all of the input files no matter if they changed
-    # maybe this behaviour can be changed to on-demand processing
-    add_custom_target(internal_pre_doc
-        ${CMAKE_COMMAND}
-        -DPROJECT_BINARY_DIR=${PROJECT_BINARY_DIR}
-        -DPROJECT_SOURCE_DIR=${PROJECT_SOURCE_DIR}
-        -Ddoc_use_external_tools=${doc_use_external_tools}
-        -P ${PROJECT_SOURCE_DIR}/scripts/cmake/DocumentationProjectFile.cmake
+if (doc_use_external_tools)
+    set(data_dir "${Data_SOURCE_DIR}")
+    add_custom_target(internal_pre_doc_qa_page
+        ${BASH_TOOL_PATH}
+        "${PROJECT_SOURCE_DIR}/scripts/doc/generate-project-file-doc-qa.sh"
+        ${PROJECT_SOURCE_DIR}
+        ${PROJECT_BINARY_DIR}
+        ${data_dir}
         WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
-        COMMENT "Generating project file documentation hierarchy." VERBATIM)
-    add_dependencies(doc internal_pre_doc)
-
-    if (doc_use_external_tools)
-        set(data_dir "${Data_SOURCE_DIR}")
-        add_custom_target(internal_pre_doc_qa_page
-            ${BASH_TOOL_PATH}
-            "${PROJECT_SOURCE_DIR}/scripts/doc/generate-project-file-doc-qa.sh"
-            ${PROJECT_SOURCE_DIR}
-            ${PROJECT_BINARY_DIR}
-            ${data_dir}
-            WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
-            COMMENT "Generating project file documentation quality assurance pages." VERBATIM)
-        add_dependencies(doc internal_pre_doc_qa_page)
-        add_dependencies(internal_pre_doc_qa_page internal_pre_doc)
-    endif()
+        COMMENT "Generating project file documentation quality assurance pages." VERBATIM)
+    add_dependencies(doc internal_pre_doc_qa_page)
+    add_dependencies(internal_pre_doc_qa_page internal_pre_doc)
 endif()

scripts/cmake/Find.cmake

@@ -2,18 +2,7 @@
 ### Find tools     ###
 ######################
 
-# Find doxygen
-if(WIN32)
-    find_program(DOXYGEN_DOT_EXECUTABLE NAMES dot
-        PATHS "$ENV{ProgramFiles}/Graphviz*/bin")
-    find_package(Doxygen QUIET)
-    if(DOXYGEN_DOT_PATH)
-        file(TO_NATIVE_PATH ${DOXYGEN_DOT_PATH} DOXYGEN_DOT_PATH)
-        set(DOXYGEN_DOT_PATH "\"${DOXYGEN_DOT_PATH}\"")
-    endif()
-else()
-    find_package(Doxygen QUIET)
-endif()
+find_package(Doxygen OPTIONAL_COMPONENTS dot)
 
 # Find gnu profiler gprof
 find_program(GPROF_PATH gprof DOC "GNU profiler gprof" QUIET)
@@ -159,7 +148,6 @@ find_package(OpenSSL)
 ## Check MPI package
 if(OGS_USE_MPI)
     find_package(MPI REQUIRED)
-    include_directories(SYSTEM ${MPI_CXX_INCLUDE_PATH})
 endif()
 
 find_package(Shapelib)

scripts/jenkins/coverage.groovy

-defaultDockerArgs = '-v /home/jenkins/.ccache:/usr/src/.ccache'
-
-def configure = new ogs.configure()
-def build = new ogs.build()
-
-def image = docker.image('ogs6/gcc-base:latest')
-image.pull()
-image.inside(defaultDockerArgs) {
-    stage('Configure (Coverage)') {
-        configure.linux(cmakeOptions: '-DOGS_COVERAGE=ON', script: this)
-    }
-
-    stage('Build (Coverage)') {
-        build.linux(
-            script: this,
-            target: 'testrunner_coverage_cobertura'
-        )
-    }
-}
-
-stage('Publish (Coverage)') {
-    step([$class: 'CoberturaPublisher', coberturaReportFile: 'build/*.xml'])
-}

scripts/jenkins/docset.groovy

-def post = new ogs.post()
-
-stage('Docset') {
-    sh("""
-    rm -rf build; mkdir build; cd build
-    cmake -DDOCS_GENERATE_DOCSET=ON ../ogs
-    cmake --build . --config Release --target doc
-
-    cd docs
-    tar --exclude='.DS_Store' -cvzf ogs6.tgz ogs6.docset
-    """.stripIndent())
-    archiveArtifacts 'build/docs/ogs6.tgz, build/docs/ogs6.xml'
-
-    post.cleanup()
-}

scripts/jenkins/gcc-tests-large.groovy

-def defaultDockerArgs = '-v /home/jenkins/.ccache:/usr/src/.ccache'
-def defaultCMakeOptions =
-    '-DCMAKE_BUILD_TYPE=Release ' +
-    '-DOGS_USE_LIS=ON'
-
-def configure = new ogs.configure()
-def build = new ogs.build()
-def post = new ogs.post()
-def helper = new ogs.helper()
-
-node('envinf11w') {
-    checkout scm
-    def image = docker.image('ogs6/gcc-gui:latest')
-    image.pull()
-    image.inside(defaultDockerArgs) {
-        stage('Configure') { configure.linux(cmakeOptions: defaultCMakeOptions,
-                                             script: this) }
-        stage('Build') { build.linux(script: this) }
-        stage('Test') { build.linux(cmd: 'make -j 1',
-                                    script: this,
-                                    target: 'tests ctest-large-serial') }
-    }
-
-    stage('Post') {
-        post.publishTestReports 'build/Testing/**/*.xml', 'build/Tests/testrunner.xml'
-        post.cleanup()
-    }
-}