diff --git a/CHANGELOG.md b/CHANGELOG.md index 514a878e..7f717aa0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,8 @@ ### Changed * Renamed `hipFileOpStatusError()` to `hipFileGetOpErrorString()` +* The `hipfile-doc` CMake target no longer exists (just use `doc`) +* The `doc` CMake target only exists if the `AIS_BUILD_DOCS` option is enabled ### Removed * The rocFile library has been completely removed and the code is now a part of hipFile. diff --git a/CMakeLists.txt b/CMakeLists.txt index 2fed842e..8be557e0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -185,7 +185,7 @@ option(AIS_BUILD_EXAMPLES "Build example programs" ON) #------ # docs #------ -option(AIS_BUILD_DOCS "Build the hipFile docs (requires Doxygen)" OFF) +include(AISDocumentation) #----------------------------------------------------------------------------- # Find important packages for building the software @@ -260,13 +260,6 @@ if(AIS_BUILD_EXAMPLES) add_subdirectory(examples/aiscp) endif() -#----------------------------------------------------------------------------- -# Configure docs -#----------------------------------------------------------------------------- -if(AIS_BUILD_DOCS) - add_subdirectory(docs) -endif() - #----------------------------------------------------------------------------- # Set up installs (must come AFTER target creation) #----------------------------------------------------------------------------- diff --git a/INSTALL.md b/INSTALL.md index 1c3196f7..bedb21de 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -121,6 +121,6 @@ want a pdf, run `make pdf` in the `latex` directory, which will create a file named refman.pdf that you can rename. If you want to build the docs without compiling the libraries, -you can just build the `doc` target: +you can just build the `doc` target (if you've set `AIS_BUILD_DOCS`): `cmake --build . --target doc` diff --git a/cmake/AISDocumentation.cmake b/cmake/AISDocumentation.cmake new file mode 100644 index 00000000..4707e06f --- /dev/null +++ b/cmake/AISDocumentation.cmake @@ -0,0 +1,40 @@ +# Copyright (c) Advanced Micro Devices, Inc. All rights reserved. +# +# SPDX-License-Identifier: MIT + +#----------------------------------------------------------------------------- +# Option to build the hipFile documentation +# +# TODO: Consider turning this into two options, one of which just requires +# Doxygen and produces API docs, the other produces Sphinx/Breathe +# output +#----------------------------------------------------------------------------- +option(AIS_BUILD_DOCS "Build the hipFile docs (requires Doxygen, Sphinx, and Breathe)" OFF) + +if(AIS_BUILD_DOCS) + find_package(Doxygen REQUIRED) + + # Set Doxygen input (pasted into Doxyfile.in) + set(AIS_DOXYFILE_INPUT "${CMAKE_SOURCE_DIR}/include") + + # Set the path to the documentation + set(AIS_DOC_PATH "${CMAKE_CURRENT_BINARY_DIR}/docs") + + # Set the Doxyfile install location + set(AIS_DOXYFILE ${AIS_DOC_PATH}/Doxyfile) + + # Create the Doxyfile from the input file + configure_file("docs/Doxyfile.in" ${AIS_DOXYFILE}) + + # Set the output directory + set(DOXYGEN_OUT ${AIS_DOC_PATH}) + + # Configure the documentation build + add_custom_target("doc" + COMMAND ${DOXYGEN_EXECUTABLE} ${AIS_DOXYFILE} + WORKING_DIRECTORY ${AIS_DOC_PATH} + COMMENT "Generating hipFile API documentation with Doxygen" + VERBATIM + ) + +endif() diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt deleted file mode 100644 index 6faf4ff4..00000000 --- a/docs/CMakeLists.txt +++ /dev/null @@ -1,54 +0,0 @@ -# Copyright (c) Advanced Micro Devices, Inc. All rights reserved. -# -# SPDX-License-Identifier: MIT - -# Documentation CMake file for AIS - -find_package(Doxygen REQUIRED) - -# The top-level doc target -add_custom_target(doc COMMENT "Building AIS documentation") - -# Add a target of the name AIS_DOC_PRETTY_NAME-doc and make -# it a dependency of the top-level doc target -# -# NOTE: The Doxyfile used in this function is optimized -# for C output and unsuitable for internal C++ -# documentation -function(ais_add_docs_target AIS_DOC_PRETTY_NAME) - # Also need the lower-case name for files, etc. - string(TOLOWER ${AIS_DOC_PRETTY_NAME} AIS_DOC_LOWER_NAME) - - # Set Doxyfile variables - set(AIS_DOXYFILE_PROJECT_NAME "${AIS_DOC_PRETTY_NAME}") - set(AIS_DOXYFILE_PROJECT_BRIEF "${AIS_DOC_PRETTY_NAME} API documentation") - set(AIS_DOXYFILE_INPUT "${CMAKE_SOURCE_DIR}/include") - - # Set the path to the documentation - set(AIS_DOC_PATH "${CMAKE_CURRENT_BINARY_DIR}/${AIS_DOC_LOWER_NAME}") - - # Set that target name - set(AIS_DOC_TARGET_NAME "${AIS_DOC_LOWER_NAME}-doc") - - # Set the Doxyfile install location - set(AIS_DOXYFILE ${AIS_DOC_PATH}/Doxyfile) - - # Create the Doxyfile from the input file - configure_file(Doxyfile.in ${AIS_DOXYFILE}) - - # Set the output directory - set(DOXYGEN_OUT ${AIS_DOC_PATH}) - - # Configure the documentation build - add_custom_target(${AIS_DOC_TARGET_NAME} - COMMAND ${DOXYGEN_EXECUTABLE} ${AIS_DOXYFILE} - WORKING_DIRECTORY ${AIS_DOC_PATH} - COMMENT "Generating ${AIS_DOC_PRETTY_NAME} API documentation with Doxygen" - VERBATIM - ) - - # Add a dependency to the top-level doc project - add_dependencies(doc ${AIS_DOC_TARGET_NAME}) -endfunction() - -ais_add_docs_target("hipFile") diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 3311de45..11f78fa6 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -42,7 +42,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "@AIS_DOXYFILE_PROJECT_NAME@" +PROJECT_NAME = "hipFile" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -54,7 +54,7 @@ PROJECT_NUMBER = @AIS_LIBRARY_VERSION@ # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = @AIS_DOXYFILE_PROJECT_BRIEF@ +PROJECT_BRIEF = "hipFile API documentation" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55