Improve documentation generation

CMakeLists.txt

@@ -12,7 +12,7 @@ set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
 
 project(Antkeeper
 	VERSION 0.0.1
-	DESCRIPTION "Ant colony simulation game"
+	DESCRIPTION "ant colony simulation game"
 	HOMEPAGE_URL "https://antkeeper.com/"
 	LANGUAGES CXX C
 )
@@ -390,5 +390,8 @@ target_link_libraries(${PROJECT_NAME}
 get_target_property(RUNTIME_OUTPUT_DIRECTORY ${PROJECT_NAME} RUNTIME_OUTPUT_DIRECTORY)
 set(DATA_OUTPUT_DIRECTORY "${RUNTIME_OUTPUT_DIRECTORY}/data")
 
-# Trigger localization CMakeLists
+# Add localization CMakeLists
 add_subdirectory(${PROJECT_SOURCE_DIR}/res/localization)
+
+# Add documentation CMakeLists
+add_subdirectory(${PROJECT_SOURCE_DIR}/docs)

README.md

@@ -20,6 +20,7 @@ Get notified when the game is released by joining the mailing list at <https://a
 
 -   [Building](#building)
     -   [Windows](#windows)
+-   [Documentation](#documentation)
 -   [Contributing](#contributing)
 -   [Authors](#authors)
 -   [License](#license)
@@ -44,6 +45,19 @@ cmake --preset windows-x64-release
 cmake --build --preset windows-x64-release
 ```
 
+## Documentation
+
+Source code documentation can be generated with [Doxygen](https://www.doxygen.nl/download.html). [Graphviz](https://graphviz.org/download/) can optionally be used to generate dependency graphs.
+
+The following commands configure and build the source code documentation:
+
+```bash
+cmake --preset windows-x64-release -DANTKEEPER_BUILD_DOCS=ON
+cmake --build --preset windows-x64-release --target docs
+```
+
+Generated HTML documentation will be located at `build/<platform>/docs/doxygen/html/index.html`.
+
 ## Contributing
 
 Contributions are welcome! Feel free to [open an issue](https://github.com/antkeeper/antkeeper/issues) or [submit a pull request](https://github.com/antkeeper/antkeeper/pulls).

docs/CMakeLists.txt

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2023 C. J. Howard
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+option(ANTKEEPER_BUILD_DOCS "Build documentation" OFF)
+
+if(ANTKEEPER_BUILD_DOCS)
+	# Find Doxygen
+	find_package(Doxygen
+		OPTIONAL_COMPONENTS
+			dot
+	)
+endif()
+
+if(ANTKEEPER_BUILD_DOCS AND DOXYGEN_FOUND)
+
+	# Download Doxygen Awesome
+	FetchContent_Declare(doxygen_awesome
+		GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css.git
+		GIT_TAG df88fe4fdd97714fadfd3ef17de0b4401f804052 # v2.3.1
+	)
+	FetchContent_MakeAvailable(doxygen_awesome)
+
+	# Generate Doxyfile
+	configure_file(${PROJECT_SOURCE_DIR}/docs/doxygen/Doxyfile.in ${PROJECT_BINARY_DIR}/docs/doxygen/Doxyfile)
+
+	# Add docs target
+	add_custom_target(docs
+		COMMAND Doxygen::doxygen ${PROJECT_BINARY_DIR}/docs/doxygen/Doxyfile
+	)
+endif()

docs/doxygen/Doxyfile → docs/doxygen/Doxyfile.in

@@ -7,11 +7,11 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = "Antkeeper"
-PROJECT_NUMBER         =
-PROJECT_BRIEF          =
+PROJECT_NAME           = "@PROJECT_NAME@"
+PROJECT_NUMBER         = "@PROJECT_VERSION@"
+PROJECT_BRIEF          = "@PROJECT_DESCRIPTION@"
 PROJECT_LOGO           =
-OUTPUT_DIRECTORY       =
+OUTPUT_DIRECTORY       = "@PROJECT_BINARY_DIR@/docs/doxygen"
 CREATE_SUBDIRS         = NO
 CREATE_SUBDIRS_LEVEL   = 8
 ALLOW_UNICODE_NAMES    = NO
@@ -31,8 +31,8 @@ ABBREVIATE_BRIEF       = "The $name class" \
                          the
 ALWAYS_DETAILED_SEC    = NO
 INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = NO
-STRIP_FROM_PATH        =
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = "@PROJECT_SOURCE_DIR@/src"
 STRIP_FROM_INC_PATH    =
 SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = YES
@@ -123,11 +123,11 @@ WARN_IF_UNDOC_ENUM_VAL = NO
 WARN_AS_ERROR          = NO
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LINE_FORMAT       = "at line $line of file $file"
-WARN_LOGFILE           = 
+WARN_LOGFILE           = "@PROJECT_BINARY_DIR@/docs/doxygen/warnings.txt"
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ../../src
+INPUT                  = "@PROJECT_SOURCE_DIR@/src"
 INPUT_ENCODING         = UTF-8
 INPUT_FILE_ENCODING    =
 FILE_PATTERNS          = *.c \
@@ -225,8 +225,8 @@ HTML_FILE_EXTENSION    = .html
 HTML_HEADER            =
 HTML_FOOTER            =
 HTML_STYLESHEET        =
-HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css \
-                         doxygen-awesome-css/doxygen-awesome-sidebar-only.css
+HTML_EXTRA_STYLESHEET  = "@doxygen_awesome_SOURCE_DIR@/doxygen-awesome.css" \
+                         "@doxygen_awesome_SOURCE_DIR@/doxygen-awesome-sidebar-only.css"
 HTML_EXTRA_FILES       =
 HTML_COLORSTYLE        = LIGHT
 HTML_COLORSTYLE_HUE    = 209
@@ -357,7 +357,7 @@ ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = NO
 EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = ../../src
+INCLUDE_PATH           = "@PROJECT_SOURCE_DIR@/src"
 INCLUDE_FILE_PATTERNS  =
 PREDEFINED             =
 EXPAND_AS_DEFINED      =