Simplify the CMake doc targets (ROCm#154)

derobins · web-flow · commit 9f84a42b2ce4 · 2026-01-09T11:21:19.000-08:00
Now that we've dropped rocFile, there's no need for a CMake function to
set up arbitrary library docs. This PR simplifies that documentation
setup by assuming that we're only building hipFile docs. It also moves
the setup from `docs/CMakeLists.txt` to `cmake/AISDocumentation.cmake`.

There are some changes to the targets:
* `hipfile-doc` no longer exists (just use `doc`)
* The `doc` target only exists if `AIS_BUILD_DOCS` is set
diff --git 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
@@ -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
@@ -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
@@ -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
diff --git 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
