Use CMake Doxygen module. (#1)

Use CMake's Doxygen support instead of invoking Doxygen directly. This makes it much clearer what configuration flags are specified that differ from the defaults.

Reviewed-on: #1
Co-authored-by: Joshua Potter <jrpotter2112@gmail.com>
Co-committed-by: Joshua Potter <jrpotter2112@gmail.com>

.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,28 @@
+find_package(Doxygen)
+
+if(DOXYGEN_FOUND)
+
+  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)
+
+endif()

docs/Doxyfile.in

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

flake.nix

@@ -24,7 +24,7 @@
             pname = "bootstrap";
             src = ./.;
             version = "0.1.3";
-            nativeBuildInputs = with pkgs; [ cmake ];
+            nativeBuildInputs = with pkgs; [ cmake doxygen ];
             installPhase = ''
               mkdir -p $out/bin
               cp ./bootstrap $out/bin

specs/clang/runner

@@ -56,7 +56,7 @@ mkdir -p "$BUILD"/build/{Debug,Release}
 # REWRITES
 # ============================================================
 
-for file in flake.nix {,src/,test/}CMakeLists.txt
+for file in flake.nix {,src/,docs/,test/}CMakeLists.txt
 do
   sed -i "s/<NAME>/$NAME/g" "$BUILD/$file"
 done

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,28 @@
+find_package(Doxygen REQUIRED)
+
+if(DOXYGEN_FOUND)
+
+  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 executable is built before documentation.
+  add_dependencies(docs "<NAME>")
+
+endif()

specs/clang/template/docs/Doxyfile.in

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

specs/clang/template/flake.nix

@@ -30,7 +30,11 @@
             pname = "<NAME>";
             src = ./.;
             version = "0.1.0";
-            nativeBuildInputs = with pkgs; [ cmake ];
+            nativeBuildInputs = with pkgs; [
+              cmake
+              # Include if interested in building documentation.
+              # doxygen
+            ];
             buildPhase = ''
               cmake -DCMAKE_BUILD_TYPE=Release .
               cmake --build .