diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 7da4e6f48e9..1bcc9623790 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -1,6 +1,9 @@ name: build-docs on: push: + branches: + - dev + - 'release-*' paths-ignore: - '.github/workflows/quarto-render.yml' - '_quarto.yml' @@ -18,11 +21,11 @@ on: - '**/.md' - 'tiledb/doxygen/source/*' - 'tiledb/sm/c_api/tiledb_version.h' + workflow_dispatch: jobs: build: runs-on: ubuntu-22.04 - if: ${{ startsWith(github.ref , 'refs/tags') != true && startsWith(github.ref , 'build-') != true }} timeout-minutes: 90 name: Build Docs steps: @@ -41,7 +44,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 - - name: Install Doxygen (linux only) + - name: Install Doxygen run: | set -e pipefail sudo apt-get update @@ -49,12 +52,10 @@ jobs: sudo apt-get install -y doxygen pip install virtualenv shell: bash - if: ${{ runner.os == 'Linux' }} - - name: Build Doxygen Docs (linux only)' + - name: Build Doxygen Docs run: | # Build the documentation (this does not deploy to RTD). cd $GITHUB_WORKSPACE/tiledb/doxygen; ./local-build.sh; shell: bash - if: ${{ runner.os == 'Linux' }} diff --git a/CMakeLists.txt b/CMakeLists.txt index 83d51e767ea..23ac97ba3cc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -40,6 +40,8 @@ include(CIConfig) include(BuildOptions) include(global-policies NO_POLICY_SCOPE) include(TileDBToolchain) +include(Doxygen) +include(Format) ############################################################ # Parse version file diff --git a/cmake/Modules/Doxygen.cmake b/cmake/Modules/Doxygen.cmake new file mode 100644 index 00000000000..a8a2467dc48 --- /dev/null +++ b/cmake/Modules/Doxygen.cmake @@ -0,0 +1,59 @@ +# +# Doxygen.cmake +# +# The MIT License +# +# Copyright (c) 2023 TileDB, Inc. +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. +# + +########################################################### +# Doxygen documentation +########################################################### + +find_package(Doxygen) +if(DOXYGEN_FOUND) + file(GLOB_RECURSE TILEDB_C_API_HEADERS "${CMAKE_SOURCE_DIR}/tiledb/*_api_external.h") + list(APPEND TILEDB_C_API_HEADERS + "${CMAKE_CURRENT_SOURCE_DIR}/tiledb/api/c_api/api_external_common.h" + "${CMAKE_CURRENT_SOURCE_DIR}/tiledb/sm/c_api/tiledb.h" + ) + file(GLOB TILEDB_CPP_API_HEADERS + "${CMAKE_CURRENT_SOURCE_DIR}/tiledb/sm/cpp_api/*.h" + ) + set(TILEDB_API_HEADERS ${TILEDB_C_API_HEADERS} ${TILEDB_CPP_API_HEADERS}) + add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxyfile.in + COMMAND mkdir -p doxygen + COMMAND echo INPUT = ${CMAKE_CURRENT_SOURCE_DIR}/tiledb/doxygen/mainpage.dox + ${TILEDB_API_HEADERS} > ${CMAKE_CURRENT_BINARY_DIR}/doxyfile.in + COMMENT "Preparing for Doxygen documentation" VERBATIM + ) + add_custom_target(doc + Doxygen::doxygen ${CMAKE_CURRENT_SOURCE_DIR}/tiledb/doxygen/Doxyfile.mk > + ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.log 2>&1 + COMMENT "Generating API documentation with Doxygen" VERBATIM + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxyfile.in + ) +else(DOXYGEN_FOUND) + add_custom_target(doc + _______doc + COMMENT "!! Docs cannot be built. Please install Doxygen and re-run cmake. !!" VERBATIM + ) +endif(DOXYGEN_FOUND) diff --git a/cmake/Modules/Format.cmake b/cmake/Modules/Format.cmake new file mode 100644 index 00000000000..81a9fbb3e3c --- /dev/null +++ b/cmake/Modules/Format.cmake @@ -0,0 +1,50 @@ +# +# Format.cmake +# +# The MIT License +# +# Copyright (c) 2023 TileDB, Inc. +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. +# + +############################################################ +# "make format" and "make check-format" targets +############################################################ + +set(SCRIPTS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/scripts") + +find_package(ClangTools) +if (NOT ${CLANG_FORMAT_FOUND}) + find_program(CLANG_FORMAT_BIN NAMES clang-format-16) + if(CLANG_FORMAT_BIN) + set(CLANG_FORMAT_FOUND TRUE) + endif() +endif() +if (${CLANG_FORMAT_FOUND}) + message(STATUS "clang hunt, found ${CLANG_FORMAT_BIN}") + # runs clang format and updates files in place. + + add_custom_target(format ${SCRIPTS_DIR}/run-clang-format.sh ${CMAKE_CURRENT_SOURCE_DIR} ${CLANG_FORMAT_BIN} 1) + + # runs clang format and exits with a non-zero exit code if any files need to be reformatted + add_custom_target(check-format ${SCRIPTS_DIR}/run-clang-format.sh ${CMAKE_CURRENT_SOURCE_DIR} ${CLANG_FORMAT_BIN} 0) +else() + message(STATUS "was unable to find clang-format") +endif() diff --git a/cmake/TileDB-Superbuild.cmake b/cmake/TileDB-Superbuild.cmake index fc3943059bb..fe60c1e0036 100644 --- a/cmake/TileDB-Superbuild.cmake +++ b/cmake/TileDB-Superbuild.cmake @@ -190,62 +190,3 @@ if (TILEDB_TESTS) WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/tiledb ) endif() - -############################################################ -# "make format" and "make check-format" targets -############################################################ - -set(SCRIPTS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/scripts") - -find_package(ClangTools) -if (NOT ${CLANG_FORMAT_FOUND}) - find_program(CLANG_FORMAT_BIN NAMES clang-format-16) - if(CLANG_FORMAT_BIN) - set(CLANG_FORMAT_FOUND TRUE) - endif() -endif() -if (${CLANG_FORMAT_FOUND}) - message(STATUS "clang hunt, found ${CLANG_FORMAT_BIN}") - # runs clang format and updates files in place. - - add_custom_target(format ${SCRIPTS_DIR}/run-clang-format.sh ${CMAKE_CURRENT_SOURCE_DIR} ${CLANG_FORMAT_BIN} 1) - - # runs clang format and exits with a non-zero exit code if any files need to be reformatted - add_custom_target(check-format ${SCRIPTS_DIR}/run-clang-format.sh ${CMAKE_CURRENT_SOURCE_DIR} ${CLANG_FORMAT_BIN} 0) -else() - message(STATUS "was unable to find clang-format") -endif() - -########################################################### -# Doxygen documentation -########################################################### - -find_package(Doxygen) -if(DOXYGEN_FOUND) - file(GLOB_RECURSE TILEDB_C_API_HEADERS "${CMAKE_SOURCE_DIR}/tiledb/*_api_external.h") - list(APPEND TILEDB_C_API_HEADERS - "${CMAKE_CURRENT_SOURCE_DIR}/tiledb/api/c_api/api_external_common.h" - "${CMAKE_CURRENT_SOURCE_DIR}/tiledb/sm/c_api/tiledb.h" - ) - file(GLOB TILEDB_CPP_API_HEADERS - "${CMAKE_CURRENT_SOURCE_DIR}/tiledb/sm/cpp_api/*.h" - ) - set(TILEDB_API_HEADERS ${TILEDB_C_API_HEADERS} ${TILEDB_CPP_API_HEADERS}) - add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxyfile.in - COMMAND mkdir -p doxygen - COMMAND echo INPUT = ${CMAKE_CURRENT_SOURCE_DIR}/tiledb/doxygen/mainpage.dox - ${TILEDB_API_HEADERS} > ${CMAKE_CURRENT_BINARY_DIR}/doxyfile.in - COMMENT "Preparing for Doxygen documentation" VERBATIM - ) - add_custom_target(doc - ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tiledb/doxygen/Doxyfile.mk > - ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.log 2>&1 - COMMENT "Generating API documentation with Doxygen" VERBATIM - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxyfile.in - ) -else(DOXYGEN_FOUND) - add_custom_target(doc - _______doc - COMMENT "!! Docs cannot be built. Please install Doxygen and re-run cmake. !!" VERBATIM - ) -endif(DOXYGEN_FOUND) diff --git a/tiledb/doxygen/README.md b/tiledb/doxygen/README.md index 6afbc1d49e9..62ee029497c 100644 --- a/tiledb/doxygen/README.md +++ b/tiledb/doxygen/README.md @@ -4,7 +4,7 @@ This directory contains the structure used to generate TileDB C and C++ API docu ## Build system integration -Doxygen is integrated in the build system via a `doc` target defined in [cmake/TileDB-Superbuild.cmake](../../cmake/TileDB-Superbuild.cmake). The `doc` target executes `doxygen` against an input file list generated by CMake into `/doxyfile.in`. `doxyfile.in` is included by `source/Doxyfile.mk`, which is specified as the config file in the CMake target definition for `doc`. This process extracts doc strings into XML files for further processing. +Doxygen is integrated in the build system via a `doc` target defined in [cmake/Modules/Doxygen.cmake](../../cmake/Modules/Doxygen.cmake). The `doc` target executes `doxygen` against an input file list generated by CMake into `/doxyfile.in`. `doxyfile.in` is included by `source/Doxyfile.mk`, which is specified as the config file in the CMake target definition for `doc`. This process extracts doc strings into XML files for further processing. ## Description of contents