Doxygen update

Author: MangaD

.github/workflows/doxygen-gh-pages.yml

@@ -11,7 +11,7 @@ on:
   workflow_dispatch:
 
 env:
-  DOXYGEN_VERSION: 1.9.7
+  DOXYGEN_VERSION: 1.14.0
 
 jobs:
   deploy:

README.md

@@ -1,12 +1,19 @@
-<div align="center">
-
 # C++ Project Template
+<!--!
+[TOC]
+-->
+<!--
+- TOC should be placed after the header
+- https://www.doxygen.nl/manual/markdown.html#md_toc
+- https://www.doxygen.nl/manual/htmlcmds.html#htmltagcmds
+-->
+<div align="center">
 
 <!--
 Cannot use relative path here because of the following Doxygen issue:
 https://github.com/doxygen/doxygen/issues/6783#issuecomment-1058486600
 -->
-<img alt="cpplogo" src="https://github.com/MangaD/cpp-project-template/blob/main/docs/doxygen/logo.png?raw=true" width="150" />
+<img alt="cpplogo" src="https://github.com/MangaD/cpp-project-template/blob/main/assets/images/logo.png?raw=true" width="150" />
 <br/><br/>
 
 

cmake/doxygen.cmake

@@ -7,50 +7,62 @@ set(DOXYGEN_ENABLE_PREPROCESSING NO) # https://stackoverflow.com/a/26043120/3049
 set(DOXYGEN_GENERATE_HTML YES CACHE BOOL "Generate Doxygen HTML")
 set(DOXYGEN_GENERATE_LATEX YES CACHE BOOL "Generate Doxygen LaTeX")
 set(DOXYGEN_GENERATE_XML YES) # Needed by Sphinx
+set(DOXYGEN_PROJECT_NAME "${PROJECT_NAME}" CACHE INTERNAL "")
+set(DOXYGEN_PROJECT_BRIEF "${PROJECT_DESCRIPTION}" CACHE INTERNAL "")
+set(DOXYGEN_PROJECT_NUMBER "${PROJECT_VERSION}" CACHE INTERNAL "")
 set(DOXYGEN_PROJECT_LOGO ${DOXYGEN_DIR}/logo.png)
+set(DOXYGEN_PROJECT_ICON ${DOXYGEN_DIR}/logo.png)
 set(DOXYGEN_OUTPUT_DIRECTORY ${DOXYGEN_DIR}/build)
+set(DOXYGEN_EXTRACT_ALL YES)
+set(DOXYGEN_EXTRACT_PRIVATE YES)
+set(DOXYGEN_EXTRACT_STATIC YES)
+set(DOXYGEN_EXTRACT_LOCAL_CLASSES YES)
+set(DOXYGEN_FULL_PATH_NAMES YES)
+set(DOXYGEN_WARN_IF_UNDOCUMENTED YES)
+set(DOXYGEN_WARN_NO_PARAMDOC YES)
+set(DOXYGEN_STRIP_FROM_PATH ${CMAKE_SOURCE_DIR})
+set(DOXYGEN_RECURSIVE YES)
 set(DOXYGEN_GENERATE_TREEVIEW YES) # Required by doxygen-awesome-css
 set(DOXYGEN_DISABLE_INDEX NO) # Required by doxygen-awesome-css
 set(DOXYGEN_FULL_SIDEBAR NO) # Required by doxygen-awesome-css
-set(DOXYGEN_HTML_COLORSTYLE LIGHT) # Required by doxygen-awesome-css
-set(DOXYGEN_HTML_HEADER ${DOXYGEN_DIR}/header.html)
-set(DOXYGEN_HTML_FOOTER ${DOXYGEN_DIR}/footer.html)
-set(DOXYGEN_HTML_EXTRA_FILES
-	${CMAKE_CURRENT_SOURCE_DIR}/LICENSE
-	${DOXYGEN_DIR}/logo.png
-	${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
-	${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
-	${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
-	${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
-	${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-tabs.js)
-set(DOXYGEN_HTML_EXTRA_STYLESHEET
-	${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome.css
-	${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-sidebar-only.css
-	${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-sidebar-only-darkmode-toggle.css)
-
-set(DOXYGEN_IMAGE_PATH ${DOXYGEN_DIR}/logo.png)
+set(DOXYGEN_HTML_COLORSTYLE "TOGGLE")
 
-if (DOXYGEN_FOUND)
-	message(STATUS "-- Doxygen documentation enabled through 'doxygen' target.")
+# === Doxygen Awesome CSS
+if(DOXYGEN_VERSION VERSION_LESS 1.14.0)
+    if(NOT EXISTS "${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome.css")
+        message(WARNING "doxygen-awesome-css submodule not found. Did you run `git submodule update --init --recursive`?")
+    endif()
+	set(DOXYGEN_HTML_COLORSTYLE LIGHT) # Required by doxygen-awesome-css
+	set(DOXYGEN_HTML_HEADER ${DOXYGEN_DIR}/header.html)
+	set(DOXYGEN_HTML_FOOTER ${DOXYGEN_DIR}/footer.html)
+	set(DOXYGEN_HTML_EXTRA_FILES
+		${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
+		${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
+		${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
+		${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
+		${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-tabs.js)
+	set(DOXYGEN_HTML_EXTRA_STYLESHEET
+		${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome.css
+		${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-sidebar-only.css
+		${DOXYGEN_DIR}/doxygen-awesome-css/doxygen-awesome-sidebar-only-darkmode-toggle.css)
+endif()
 
-	# Add Table of Contents to markdown files
-	file(GLOB md_files ${CMAKE_SOURCE_DIR}/docs/*.md)
 
-    file(COPY ${CMAKE_SOURCE_DIR}/README.md DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/md_files")
-	file(COPY ${md_files} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/md_files/docs")
+if (DOXYGEN_FOUND)
+	message(STATUS "-- Doxygen documentation enabled through 'doxygen' target.")
 
-    file(GLOB_RECURSE md_files "${CMAKE_CURRENT_BINARY_DIR}/md_files/*.md")
-    foreach(filename ${md_files})
-        file(READ ${filename} MD_TEXT)
-        # Insert [TOC] immediately after the first level-1 header line.
-        string(REGEX REPLACE "^(# [^\n]+)\r?\n(.+)" "\\1\n[TOC]\n\\2" MD_TEXT_MODIFIED "${MD_TEXT}")
-        file(WRITE ${filename} "${MD_TEXT_MODIFIED}")
-    endforeach()
+	set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md")
+	file(GLOB md_files "${CMAKE_SOURCE_DIR}/docs/*.md")
 
-	set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_CURRENT_BINARY_DIR}/md_files/README.md")
+	# Make these files available to Doxygen
+	set(DOXYGEN_HTML_EXTRA_FILES
+		${DOXYGEN_HTML_EXTRA_FILES}
+		${CMAKE_SOURCE_DIR}/LICENSE
+	)
 
 	doxygen_add_docs(doxygen
 		${md_files}
+		README.md
 		LICENSE
 		${SOURCE_DIR})
 endif()