From 6692e203a2e59e80141f8b032de9adebf44c9230 Mon Sep 17 00:00:00 2001 From: Virginie Grandgirard Date: Mon, 25 Mar 2024 18:37:47 +0000 Subject: [PATCH] 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 | 8 +------- .gitlab-ci.yml | 12 +++--------- CMakeLists.txt | 38 ++++++++++++++++++++++++++----------- docs/Adding_docs.md | 14 +++++++++++++- 4 files changed, 44 insertions(+), 28 deletions(-) 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.