Use CMake Doxygen package from clang.

.gitignore

@@ -7,9 +7,6 @@
 # The directory containing all build outputs.
 /build/
 
-# The directory generated by `Doxygen`.
-/docs/
-
 # A symlink produced by default when running `nix build`.
 result
 

CMakeLists.txt

@@ -2,11 +2,12 @@ cmake_minimum_required(VERSION 3.19)
 project(bootstrap VERSION 0.1.3 LANGUAGES C)
 
 add_executable(bootstrap main.c)
-
-add_subdirectory(src)
 target_link_libraries(bootstrap PUBLIC m)
 target_include_directories(bootstrap PUBLIC include)
 
+add_subdirectory(src)
+add_subdirectory(docs)
+
 if("${CMAKE_BUILD_TYPE}" STREQUAL "Debug")
   set_target_properties(
     bootstrap PROPERTIES

README.md

@@ -251,10 +251,12 @@ $ make test
 
 ### Documentation
 
-We use [doxygen](https://www.doxygen.nl/index.html) for documentation
-generation. Run the following command to generate documentation locally:
+Documentation is generated using [Doxygen](https://www.doxygen.nl/index.html)
+(version 1.9.7) through CMake. (Re)generate documentation by navigating to
+the desired build configuration directory and running:
 ```bash
-$ doxygen
+$ cmake --build .
+$ make docs
 ```
 
 ### Formatting

docs/CMakeLists.txt

@@ -0,0 +1,24 @@
+find_package(Doxygen REQUIRED)
+
+set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/include)
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+
+add_custom_command(OUTPUT
+  ${DOXYGEN_INDEX_FILE}
+  COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+  MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+  COMMENT "Generating Doxygen documentation"
+  VERBATIM
+)
+
+add_custom_target(docs DEPENDS ${DOXYGEN_INDEX_FILE})
+
+# Ensure worker is built before documentation.
+add_dependencies(docs bootstrap)

docs/Doxyfile.in

@@ -0,0 +1,2 @@
+INPUT                  = "@DOXYGEN_INPUT_DIR@"
+GENERATE_LATEX         = NO

specs/clang/template/.gitignore

@@ -7,9 +7,6 @@
 # The directory containing all build outputs.
 /build/
 
-# The directory generated by `Doxygen`.
-/docs/
-
 # A symlink produced by default when running `nix build`.
 /result
 

specs/clang/template/CMakeLists.txt

@@ -15,6 +15,9 @@ add_executable("<NAME>" main.c)
 # for linking the other project source files to our executable.
 add_subdirectory(src)
 
+# Use the Doxygen module to generate documentation through CMake.
+add_subdirectory(docs)
+
 # An example on linking additional libraries. In this case, links `math`.
 target_link_libraries("<NAME>" PUBLIC m)
 

specs/clang/template/README.md

@@ -41,10 +41,11 @@ exists and points to this generated database.
 ## Documentation
 
 Documentation is generated using [Doxygen](https://www.doxygen.nl/index.html)
-(version 1.9.7). (Re)generate documentation by editing the `Doxyfile` and
-running:
+(version 1.9.7) through CMake. (Re)generate documentation by navigating to
+the desired build configuration directory and running:
 ```bash
-$ doxygen
+$ cmake --build .
+$ make docs
 ```
 
 ## Testing

specs/clang/template/docs/CMakeLists.txt

@@ -0,0 +1,24 @@
+find_package(Doxygen REQUIRED)
+
+set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/include)
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+
+add_custom_command(OUTPUT
+  ${DOXYGEN_INDEX_FILE}
+  COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+  MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+  COMMENT "Generating Doxygen documentation"
+  VERBATIM
+)
+
+add_custom_target(docs DEPENDS ${DOXYGEN_INDEX_FILE})
+
+# Ensure worker is built before documentation.
+add_dependencies(docs bootstrap)

specs/clang/template/docs/Doxyfile.in

@@ -0,0 +1 @@
+INPUT                  = "@DOXYGEN_INPUT_DIR@"