CMake documentation builds (#583)

* 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 <[email protected]>

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

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.

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()

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()

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}
+)