From 4f6930115115a91ae07896454772cf2a2539006d Mon Sep 17 00:00:00 2001 From: Sam Wu <22262939+samjwu@users.noreply.github.com> Date: Thu, 11 Jul 2024 08:29:12 -0600 Subject: [PATCH] CMake documentation builds (#583) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Automate doc builds using CMake * Update rocm-docs-core * Multi-config friendly summary * Add USES_DOXYGEN * Bump rocm-cmake version requirement * Update README regarding docs * Update rocm-cmake version used * Correct pip compile cmd --------- Co-authored-by: Máté Ferenc Nagy-Egri --- CMakeLists.txt | 6 ++++++ README.md | 35 +++++++++++++++++++++++++++++++---- cmake/Dependencies.cmake | 10 +++++++--- cmake/Summary.cmake | 8 +++++++- docs/CMakeLists.txt | 37 +++++++++++++++++++++++++++++++++++++ 5 files changed, 88 insertions(+), 8 deletions(-) create mode 100644 docs/CMakeLists.txt diff --git a/CMakeLists.txt b/CMakeLists.txt index 54c98d083..9da8ff7cb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -46,6 +46,7 @@ endif() option(BUILD_TEST "Build tests (requires googletest)" OFF) option(BUILD_BENCHMARK "Build benchmarks" OFF) option(BUILD_EXAMPLE "Build examples" OFF) +option(BUILD_DOCS "Build documentation (requires sphinx)" OFF) option(USE_HIP_CPU "Prefer HIP-CPU runtime instead of HW acceleration" OFF) # Disables building tests, benchmarks, examples option(ONLY_INSTALL "Only install" OFF) @@ -165,6 +166,11 @@ if(BUILD_EXAMPLE AND NOT ONLY_INSTALL) add_subdirectory(example) endif() +# Docs +if(BUILD_DOCS AND NOT ONLY_INSTALL) + add_subdirectory(docs) +endif() + # Package if (ROCPRIM_PROJECT_IS_TOP_LEVEL) set(BUILD_SHARED_LIBS ON) # Build as though shared library for naming diff --git a/README.md b/README.md index ec23889eb..ea8640f95 100644 --- a/README.md +++ b/README.md @@ -30,23 +30,50 @@ Optional: Documentation for rocPRIM is available at [https://rocm.docs.amd.com/projects/rocPRIM/en/latest/](https://rocm.docs.amd.com/projects/rocPRIM/en/latest/). -To build our documentation locally, use the following code: +### Build documentation locally ```shell -# Go to rocPRIM docs directory +# Change directory to rocPRIM docs cd rocPRIM; cd docs -# Install Python dependencies +# Install documentation dependencies python3 -m pip install -r sphinx/requirements.txt # Build the documentation python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html -# For local HTML version +# To serve the HTML docs locally cd _build/html python3 -m http.server ``` +### Build documentation via CMake + +Install [rocm-cmake](https://github.com/ROCm/rocm-cmake/) + +```shell +# Change directory to rocPRIM +cd rocPRIM + +# Install documentation dependencies +python3 -m pip install -r docs/sphinx/requirements.txt + +# Set C++ compiler +# This example uses hipcc and assumes it is at the path /usr/bin +export CXX=hipcc +export PATH=/usr/bin:$PATH + +# Configure the project +cmake -S . -B ./build -D BUILD_DOCS=ON + +# Build the documentation +cmake --build ./build --target doc + +# To serve the HTML docs locally +cd ./build/docs/html +python3 -m http.server +``` + ## Build and install You can build and install rocPRIM on Linux or Windows. diff --git a/cmake/Dependencies.cmake b/cmake/Dependencies.cmake index e5ce38c60..1abe538a9 100644 --- a/cmake/Dependencies.cmake +++ b/cmake/Dependencies.cmake @@ -175,7 +175,7 @@ if(BUILD_BENCHMARK) endif(BUILD_BENCHMARK) if(NOT DEPENDENCIES_FORCE_DOWNLOAD) - find_package(ROCM 0.7.3 CONFIG QUIET PATHS "${ROCM_ROOT}") + find_package(ROCM 0.12.0 CONFIG QUIET PATHS "${ROCM_ROOT}") # rocm-cmake endif() if(NOT ROCM_FOUND) message(STATUS "ROCm CMake not found. Fetching...") @@ -189,13 +189,14 @@ if(NOT ROCM_FOUND) set(rocm_cmake_tag "master" CACHE STRING "rocm-cmake tag to download") FetchContent_Declare( rocm-cmake - URL https://github.com/RadeonOpenCompute/rocm-cmake/archive/${rocm_cmake_tag}.tar.gz + GIT_REPOSITORY https://github.com/ROCm/rocm-cmake.git + GIT_TAG rocm-6.1.2 ${SOURCE_SUBDIR_ARG} ) FetchContent_MakeAvailable(rocm-cmake) find_package(ROCM CONFIG REQUIRED NO_DEFAULT_PATH PATHS "${rocm-cmake_SOURCE_DIR}") else() - find_package(ROCM 0.7.3 CONFIG REQUIRED PATHS "${ROCM_ROOT}") + find_package(ROCM 0.12.0 CONFIG REQUIRED PATHS "${ROCM_ROOT}") endif() # Restore user global state @@ -215,3 +216,6 @@ include(ROCMInstallSymlinks) include(ROCMHeaderWrapper) include(ROCMCheckTargetIds) include(ROCMClients) +if(BUILD_DOCS) + include(ROCMSphinxDoc) +endif() diff --git a/cmake/Summary.cmake b/cmake/Summary.cmake index e40888ae6..462ed2f99 100644 --- a/cmake/Summary.cmake +++ b/cmake/Summary.cmake @@ -29,7 +29,12 @@ function(print_configuration_summary) message(STATUS " C++ compiler version : ${CMAKE_CXX_COMPILER_VERSION}") string(STRIP "${CMAKE_CXX_FLAGS}" CMAKE_CXX_FLAGS_STRIP) message(STATUS " CXX flags : ${CMAKE_CXX_FLAGS_STRIP}") - message(STATUS " Build type : ${CMAKE_BUILD_TYPE}") + get_property(GENERATOR_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG) + if(GENERATOR_IS_MULTI_CONFIG) + message(STATUS " Build types : ${CMAKE_CONFIGURATION_TYPES}") + else() + message(STATUS " Build type : ${CMAKE_BUILD_TYPE}") + endif() message(STATUS " Install prefix : ${CMAKE_INSTALL_PREFIX}") if(NOT USE_HIP_CPU) message(STATUS " Device targets : ${GPU_TARGETS}") @@ -39,5 +44,6 @@ function(print_configuration_summary) message(STATUS " BUILD_TEST : ${BUILD_TEST}") message(STATUS " BUILD_BENCHMARK : ${BUILD_BENCHMARK}") message(STATUS " BUILD_EXAMPLE : ${BUILD_EXAMPLE}") + message(STATUS " BUILD_DOCS : ${BUILD_DOCS}") message(STATUS " USE_HIP_CPU : ${USE_HIP_CPU}") endfunction() diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 000000000..b41862c02 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,37 @@ +# MIT License +# +# Copyright (c) 2017-2024 Advanced Micro Devices, Inc. All rights reserved. +# +# 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. + +# rocPRIM documentation + +include(GNUInstallDirs) + +rocm_add_sphinx_doc( + "${CMAKE_CURRENT_SOURCE_DIR}" + BUILDER html + OUTPUT_DIR html + USES_DOXYGEN +) + +install( + DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html" + DESTINATION ${CMAKE_INSTALL_DOCDIR} +)