Enable easy local documentation compilation

Allow the generation of the documentation website locally while only requiring the installation of doxygen. Use this new configuration to simplify the CI scripts. Update documentation to describe how to generate the documentation locally. Fixes #187

See merge request gysela-developpers/gyselalibxx!416

--------------------------------------------

.github/workflows/tests.yml

@@ -89,15 +89,9 @@ jobs:
     if: github.event_name == 'push' && github.ref_name == 'main'
     needs: docker
     runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/gyselax/gyselalibxx_env:${{ github.sha }}
-      options: --user root
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
-        with:
-          path: code_branch
-          submodules: recursive
       - name: Checkout documentation
         uses: actions/checkout@v3
         with:
@@ -107,7 +101,7 @@ jobs:
         run: |
           mkdir build
           cd build
-          cmake -DBUILD_DOCUMENTATION=ON ../code_branch
+          cmake -DGYSELALIBXX_COMPILE_SOURCE=OFF -DBUILD_DOCUMENTATION=1 ../code_branch
           make doc
         shell: bash
       - name: Update documentation

.gitlab-ci.yml

@@ -130,24 +130,18 @@ documentation:
   stage: test
   needs: []
   image: ghcr.io/gyselax/gyselalibxx_env
-  variables:
-    GIT_SUBMODULE_STRATEGY: recursive
   before_script: |
     git config --global --add safe.directory $CI_PROJECT_DIR
     git fetch origin ${CI_MERGE_REQUEST_TARGET_BRANCH_NAME} --recurse-submodules=no
   script: |
-    git config --global --add safe.directory /builds/gysela-developpers/gyselalibxx/vendor/kokkos
     rm -rf build || true
     # Make docs
-    mkdir build
-    cd build
-    cmake -DCMAKE_CXX_FLAGS=-Wall -DBUILD_DOCUMENTATION=ON -DKokkos_ENABLE_DEPRECATED_CODE_3=OFF -DKokkos_ENABLE_DEPRECATION_WARNINGS=OFF ..
-    make doc
-    cd ..
+    cmake -DGYSELALIBXX_COMPILE_SOURCE=OFF -DBUILD_DOCUMENTATION=1 -B build-docs .
+    cmake --build build-docs
     # Get files which have changed in this merge request
     git diff origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}..HEAD --no-indent-heuristic --unified=0 --output=pull_diff.txt --no-color
     # Filter documentation messages to only complain about modified files
-    python3 ci_tools/check_documentation.py pull_diff.txt build/docs/doxygen.log
+    python3 ci_tools/check_documentation.py pull_diff.txt build-docs/docs/doxygen.log
     git diff origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}..HEAD --no-indent-heuristic --unified=0 --output=pull_new_files.txt --no-color --diff-filter=A
     python3 ci_tools/check_readme_presence.py pull_new_files.txt
   allow_failure: true

CMakeLists.txt

@@ -18,6 +18,7 @@ set(CMAKE_CXX_STANDARD 17 CACHE INTERNAL "The C++ standard whose features are re
 option(BUILD_BENCHMARKS "Build the benchmarks." OFF)
 option(BUILD_DOCUMENTATION "Build the documentation." OFF)
 option(GYSELALIBXX_ENABLE_DEPRECATED "Enable deprecated code" OFF)
+option(GYSELALIBXX_COMPILE_SOURCE "Enable compilation of the source code (this should be set to off to build documentation without the C++ dependencies)" ON)
 set(GYSELALIBXX_DEFAULT_CXX_FLAGS "-O1" CACHE STRING "Default flags for C++ specific to Voice++")
 
 set(GYSELALIBXX_DEPENDENCY_POLICIES "AUTO" "EMBEDDED" "INSTALLED")
@@ -28,6 +29,27 @@ option(DDC_BUILD_DOCUMENTATION    "Build DDC documentation/website" OFF)
 option(DDC_BUILD_EXAMPLES         "Build DDC examples" OFF)
 option(DDC_BUILD_TESTS            "Build DDC tests if BUILD_TESTING is enabled" OFF)
 
+###############################################################################################
+#                                  Build documentation
+###############################################################################################
+
+## if documentation is enabled, build it
+if("${BUILD_DOCUMENTATION}")
+  ## Look for a pre-installed Doxygen
+  find_package(Doxygen REQUIRED OPTIONAL_COMPONENTS dot)
+
+  add_subdirectory(docs/)
+endif()
+
+## Turn off documentation for subpackages
+set(BUILD_DOCUMENTATION OFF)
+
+###############################################################################################
+#                                     Get dependencies
+###############################################################################################
+
+if ("${GYSELALIBXX_COMPILE_SOURCE}")
+
 # Our dependencies
 
 ## Use CTest for running tests
@@ -100,17 +122,6 @@ elseif("${GYSELALIBXX_mdspan_DEPENDENCY_POLICY}" STREQUAL "INSTALLED")
   find_package(mdspan "0.3" REQUIRED)
 endif()
 
-## if documentation is enabled, build it
-if("${BUILD_DOCUMENTATION}")
-  ## Look for a pre-installed Doxygen
-  find_package(Doxygen REQUIRED OPTIONAL_COMPONENTS dot)
-
-  add_subdirectory(docs/)
-endif()
-
-## Turn off documentation for subpackages
-set(BUILD_DOCUMENTATION OFF)
-
 ## Use Kokkos from `vendor/`
 if("${Kokkos_ENABLE_CUDA}")
   option(Kokkos_ENABLE_CUDA_CONSTEXPR "Whether to activate experimental relaxed constexpr functions" ON)
@@ -143,6 +154,9 @@ add_subdirectory("vendor/kokkos-tools/profiling/simple-kernel-timer/" "kokkos-to
 set(BUILD_SHARED_LIBS "${BUILD_SHARED_LIBS_DUMP}")
 add_compile_definitions(KP_KERNEL_TIMER_PATH="${CMAKE_CURRENT_BINARY_DIR}/kokkos-tools/profiling/simple-kernel-timer/libkp_kernel_timer.so")
 
+###############################################################################################
+#                              Build libraries and executables
+###############################################################################################
 # Our project code
 
 ## Change the C++ flags to the voice specific ones
@@ -160,3 +174,5 @@ add_subdirectory(simulations/)
 if("${BUILD_TESTING}")
     add_subdirectory(tests/)
 endif()
+
+endif() # GYSELALIBXX_COMPILE_SOURCE

docs/Adding_docs.md

@@ -1,9 +1,21 @@
 # Adding Documentation
 
-There are two types of documentation:
+There are two types of documentation which are described in detail below:
 1.  Documentation describing code structures
 2.  Documentation describing general methods
 
+## Building documentation locally
+
+The documentation can be built locally by running the following commands from the root directory:
+```
+cmake -DGYSELALIBXX_COMPILE_SOURCE=OFF -DBUILD_DOCUMENTATION=1 -B build-docs .
+cmake --build build-docs
+```
+The option `-DGYSELALIBXX_COMPILE_SOURCE=OFF` ensures that the C++ code is not built, thereby avoiding the need to have all the C++ dependencies installed on your system.
+If this option is not used then `make docs` should be used to build only the documentation.
+
+In order to view the docs the file `build-docs/docs/html/index.html` should be opened in a browser (e.g. Firefox).
+
 ## Documentation describing code structures
 
 This documentation should be added next to the code it is describing.