diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 867d748ef..c6bf6921f 100644 --- a/.github/workflows/tests.yml +++ b/.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 diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index dd877ec5a..98d97683d 100644 --- a/.gitlab-ci.yml +++ b/.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 diff --git a/CMakeLists.txt b/CMakeLists.txt index 2e8c0776f..d73ad625e 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/docs/Adding_docs.md b/docs/Adding_docs.md index 7461a2d81..3509b0cc9 100644 --- a/docs/Adding_docs.md +++ b/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.