adding doxygen-sphinx build

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: documentation
+
+on: [pull_request]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Doxygen Build
+        uses: ryandanehy/sphinx-doxygen@v1
+        with:
+           sphinx-path: './sphinx/_build'
+           working-directory: 'docs'
+           doxyfile-path: './doxygen/Doxyfile.in'
+      - uses: actions/setup-python@v3
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'pull_request' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/sphinx/_build/
+          force_orphan: true

.gitignore

@@ -1,5 +1,6 @@
 .vscode/
 build/*
+_build
 install/*
 *~
 *.swp

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "buildsystem/spack/spack"]
 	path = buildsystem/spack/spack
 	url = https://github.com/cameronrutherford/spack.git
+[submodule "doxygen-awesome-css"]
+	path = docs/doxygen/doxygen-awesome-css/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

CMakeLists.txt

@@ -29,6 +29,9 @@ option(RESOLVE_USE_HIP  "Use HIP language and ROCm library" OFF)
 option(RESOLVE_USE_GPU  "Use GPU device for computations" OFF)
 mark_as_advanced(FORCE RESOLVE_USE_GPU)
 
+option(RESOLVE_USE_DOXYGEN "Use Doxygen to generate Re::Solve documentation" ON)
+set(RESOLVE_CTEST_OUTPUT_DIR ${PROJECT_BINARY_DIR} CACHE PATH "Directory where CTest outputs are saved")
+
 if(RESOLVE_USE_CUDA)
   set(RESOLVE_USE_GPU ON CACHE BOOL "Using CUDA GPU!" FORCE)
 endif()
@@ -48,6 +51,48 @@ set(CMAKE_INSTALL_RPATH ${CMAKE_INSTALL_PREFIX}/lib)
 # Add CMake sources from `cmake` dir
 list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
 
+# Including clang-format cmake files to do automatic checking of formating
+# TODO: Set up clang-format
+#include(./cmake/clang-format)
+
+if (RESOLVE_USE_DOXYGEN)
+  find_package(Doxygen)
+endif()
+
+if ( DOXYGEN_FOUND )
+  set( DOXYGEN_OUTPUT_DIRECTORY ./sphinx/_build/doxygen )
+  set( DOXYGEN_COLLABORATION_GRAPH YES )
+  set( DOXYGEN_EXTRACT_ALL YES )
+  set( DOXYGEN_CLASS_DIAGRAMS YES )
+  set( DOXYGEN_HIDE_UNDOC_RELATIONS NO )
+  set( DOXYGEN_HAVE_DOT YES )
+  set( DOXYGEN_CLASS_GRAPH YES )
+  set( DOXYGEN_CALL_GRAPH YES )
+  set( DOXYGEN_CALLER_GRAPH YES )
+  set( DOXYGEN_COLLABORATION_GRAPH YES )
+  set( DOXYGEN_BUILTIN_STL_SUPPORT YES )
+  set( DOXYGEN_EXTRACT_PRIVATE YES )
+  set( DOXYGEN_EXTRACT_PACKAGE YES )
+  set( DOXYGEN_EXTRACT_STATIC YES )
+  set( DOXYGEN_EXTRACT_LOCALMETHODS YES )
+  set( DOXYGEN_UML_LOOK YES )
+  set( DOXYGEN_UML_LIMIT_NUM_FIELDS 50 )
+  set( DOXYGEN_TEMPLATE_RELATIONS YES )
+  set( DOXYGEN_DOT_GRAPH_MAX_NODES 100 )
+  set( DOXYGEN_MAX_DOT_GRAPH_DEPTH 0 )
+  set( DOXYGEN_DOT_TRANSPARENT YES )
+  set(DOXYGEN_DISABLE_INDEX NO)
+  set(DOXYGEN_FULL_SIDEBAR NO)
+  set(DOXYGEN_GENERATE_TREEVIEW YES)
+  set(DOXYGEN_HTML_EXTRA_STYLESHEET "./docs/doxygen/doxygen-awesome-css/doxygen-awesome.css")
+  set(DOXYGEN_HTML_COLORSTYLE LIGHT)
+  doxygen_add_docs( doxygen ${RPP_PROJECT_SOURCE_DIR} )
+
+else()
+  message( "Doxygen need to be installed to generate the doxygen documentation" )
+endif()
+
+
 if (RESOLVE_USE_KLU)
   include(FindKLU)
   if(NOT KLU_LIBRARY)

README.md

@@ -2,6 +2,8 @@
 
 ReSolve is a library of GPU-resident linear solver. It contains iterative and direct linear solvers designed to run on NVIDIA and AMD GPUs, as well as on CPU devices.
 
+ReadTheDocs Documentation lives here https://ornl.github.io/ReSolve/
+
 ## Getting started
 
 Dependencies:

cmake/ReSolveAddLibrary.cmake

@@ -0,0 +1,150 @@
+#[[#############################################################################
+
+ReSolveAddLibrary.cmake
+
+@author Cameron Rutherford <cameron.rutherford@pnnl.gov>
+@remark This file exports the following: exago_add_library. The macro
+  described here should allow all libraries in any CMakeLists.txt to be
+  written identically.
+@remark Using a marco instead of a function as none of the inputs to
+  the macro should be modified in any capacity.
+
+#]]
+# ##############################################################################
+
+#[[
+
+@brief Creates an object library + shared/static library
+@param OUTPUT_NAME : Specifies the output name of the library to be created
+@param SOURCES : List of source files used to create the library
+@param HEADERS : List of header files to install with the library
+@param INCLUDE_SUBDIR : optional subdirectory for headers to be installed
+@param LINK_LIBRARIES : List of libraries that are linked against using
+  target_link_libraries for each target within the macro
+
+#]]
+
+macro(exago_add_library target)
+  set(options STATIC_ONLY SHARED_ONLY)
+  set(oneValueArgs OUTPUT_NAME INCLUDE_SUBDIR)
+  set(multiValueArgs SOURCES HEADERS LINK_LIBRARIES)
+
+  # Parse arguments
+  cmake_parse_arguments(
+    exago_add_library "${options}" "${oneValueArgs}" "${multiValueArgs}"
+    ${ARGN}
+  )
+
+  # Library types that we want to create.
+  set(_libtypes "")
+  # Build shared lib first, as alias library should prefer linking shared lib.
+  if(EXAGO_BUILD_SHARED)
+    set(_libtypes "SHARED")
+  endif()
+  if(EXAGO_BUILD_STATIC)
+    set(_libtypes "${_libtypes};STATIC")
+  endif()
+
+  # Build Libraries
+  foreach(_libtype ${_libtypes})
+    # Add library suffix so internal library names are unique
+    if(${_libtype} MATCHES "STATIC")
+      set(_lib_suffix "_static")
+    else()
+      set(_lib_suffix "_shared")
+    endif()
+
+    # Source files for target
+    set(sources ${exago_add_library_SOURCES})
+
+    # Obj target also needs a unique name
+    set(obj_target ${target}_obj${_lib_suffix})
+
+    # -- Create object library --
+
+    add_library(${obj_target} OBJECT ${sources})
+
+    if(exago_add_library_LINK_LIBRARIES)
+      if(${_lib_type} MATCHES "STATIC")
+        append_static_suffix(exago_add_library_LINK_LIBRARIES _all_libs)
+      else()
+        set(_all_libs ${exago_add_library_LINK_LIBRARIES})
+      endif()
+      target_link_libraries(${obj_target} ${_all_libs})
+    endif()
+
+    # Object libraries need PIC code enabled
+    set_target_properties(
+      ${obj_target} PROPERTIES POSITION_INDEPENDENT_CODE TRUE
+    )
+
+    set(_actual_target_name ${target}${_lib_suffix})
+
+    add_library(
+      ${_actual_target_name} ${_libtype} $<TARGET_OBJECTS:${obj_target}>
+    )
+
+    if(exago_add_library_LINK_LIBRARIES)
+      target_link_libraries(
+        ${_actual_target_name} ${exago_add_library_LINK_LIBRARIES}
+      )
+    endif()
+
+    # Generic Include directories to be added Bulding : public, config/export
+    # and shared/private headers Installing: installed include directory Can
+    # also add macro option INCLUDE_DIRECTORIES to customize this
+    target_include_directories(
+      ${_actual_target_name}
+      PUBLIC $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+             $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/include>
+             $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include/private>
+             $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+    )
+
+    # Enabling namespace usage with exported targets Check for existing target
+    # (can't create same alias for shared + static)
+    if(NOT TARGET ExaGO::${target})
+      add_library(ExaGO::${target} ALIAS ${_actual_target_name})
+    endif()
+
+    if(exago_add_library_OUTPUT_NAME)
+      set_target_properties(
+        ${_actual_target_name}
+        PROPERTIES OUTPUT_NAME ${exago_add_library_OUTPUT_NAME}
+                   CLEAN_DIRECT_OUTPUT 1
+      )
+    else()
+      set_target_properties(
+        ${_actual_target_name} PROPERTIES OUTPUT_NAME ${target}
+                                          CLEAN_DIRECT_OUTPUT 1
+      )
+    endif()
+
+    install(
+      TARGETS ${_actual_target_name}
+      DESTINATION lib
+      EXPORT exago-targets
+    )
+
+    # Install header files
+    if(exago_add_library_HEADERS)
+      install(FILES ${exago_add_library_HEADERS}
+              DESTINATION "include/${exago_add_library_INCLUDE_SUBDIR}"
+      )
+    endif()
+
+  endforeach()
+endmacro()
+
+# Macro to append static suffix to library names Currently using hard coded
+# "_shared" but this can be changed
+macro(append_static_suffix libs_in libs_out)
+  set(_STATIC_LIB_SUFFIX "_static")
+  set(${libs_out} "")
+  foreach(_lib ${${libs_in}})
+    if(TARGET ${_lib}${_STATIC_LIB_SUFFIX})
+      list(APPEND ${libs_out} ${_lib}${_STATIC_LIB_SUFFIX})
+    else()
+      list(APPEND ${libs_out} ${_lib})
+    endif()
+  endforeach()