docs: Improve Doxygen Visuals and Build process

- Switched to CMake for configuring and building the doxygen Website. - Set the minimum requirements to CMake >=3.18.4 and Doxygen >=1.9.1. - Rewrite the LICENSE.txt and docs README.txt to markdown. - Add the folder which is used in the README to gitignore. - Add a custom style to the doxygen website based on the docs webpage. - Update CI to use the new Doxygen Build process. Closes #7052
2024-09-27 00:10:40 +02:00
parent 75da070076
commit 19aca9fe74
11 changed files with 210 additions and 142 deletions
@@ -0,0 +1,12 @@
+# 0ad Documentation
+
+- Lots of general documentation is on the Gitea wiki: https://gitea.wildfiregames.com/0ad/0ad/wiki
+
+- Doxygen documentation is published at https://docs.wildfiregames.com/pyrogenesis/
+
+## Building the Doxygen documentation
+
+To generate the Doxygen documentation: run "cmake -S . -B output && cmake --build output".
+
+If you build the documentation with cmake, the output is located in the folder html inside your
+specified build directory.
@@ -1,5 +0,0 @@
-Lots of general documentation is on Trac: http://trac.wildfiregames.com/
-
-Doxygen documentation is at http://svn.wildfiregames.com/docs/
-
-To generate the Doxygen documentation: run "doxygen config" in docs/doxygen/
@@ -0,0 +1,65 @@
+cmake_minimum_required(VERSION 3.18.4...3.28.0)
+
+project(Pyrogenesis DESCRIPTION "Pyrogenesis, a RTS Engine" LANGUAGES NONE)
+
+# Check if Doxygen and graphviz are installed.
+find_package(Doxygen 1.9.1 REQUIRED dot)
+
+if(DOXYGEN_FOUND)
+
+    include(FetchContent)
+
+    FetchContent_Declare(doxygen_awesome_css
+        GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css
+        GIT_TAG        v2.3.3
+        SOURCE_DIR     ${CMAKE_CURRENT_BINARY_DIR}/styling
+    )
+    FetchContent_MakeAvailable(doxygen_awesome_css)
+
+    # Get current Branch Name to set it as the Project Number.
+    find_package(Git)
+    if(Git_FOUND)
+        set(ENV{GIT_DISCOVERY_ACROSS_FILESYSTEM} 1)
+        execute_process(COMMAND "${GIT_EXECUTABLE}" rev-parse --is-inside-work-tree OUTPUT_VARIABLE IS_GIT OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
+        if(IS_GIT)
+            execute_process(COMMAND "${GIT_EXECUTABLE}" rev-parse --abbrev-ref HEAD OUTPUT_VARIABLE CURRENT_BRANCH OUTPUT_STRIP_TRAILING_WHITESPACE)
+        endif()
+    endif()
+
+    # Doxygen Configuration.
+    if(CURRENT_BRANCH)
+        set(DOXYGEN_PROJECT_NUMBER ${CURRENT_BRANCH})
+    else()
+        set(DOXYGEN_PROJECT_NUMBER main)
+    endif()
+    set(DOXYGEN_PROJECT_LOGO ${CMAKE_CURRENT_SOURCE_DIR}/pyrogenesis.png)
+    set(DOXYGEN_TAB_SIZE 4)
+    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${CMAKE_CURRENT_SOURCE_DIR}/Main-Page.md)
+    set(DOXYGEN_EXCLUDE_PATTERNS */.svn* */tests/test_*)
+    set(DOXYGEN_INCLUDE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../../source)
+    set(DOXYGEN_EXAMPLE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../../source)
+    set(DOXYGEN_EXCLUDE ${CMAKE_CURRENT_SOURCE_DIR}/../../source/tools ${CMAKE_CURRENT_SOURCE_DIR}/../../source/third_party)
+    set(DOXYGEN_GENERATE_TREEVIEW YES)
+    set(DOXYGEN_HTML_EXTRA_STYLESHEET ${doxygen_awesome_css_SOURCE_DIR}/doxygen-awesome.css ${CMAKE_CURRENT_SOURCE_DIR}/style.css)
+    set(DOXYGEN_JAVADOC_AUTOBRIEF YES)
+    set(DOXYGEN_EXTRACT_ALL YES)
+    set(DOXYGEN_EXTRACT_PRIVATE YES)
+    set(DOXYGEN_EXTRACT_STATIC YES)
+    set(DOXYGEN_EXTRACT_ANON_NSPACES YES)
+    set(DOXYGEN_SHOW_DIRECTORIES YES)
+    set(DOXYGEN_STRIP_CODE_COMMENTS NO)
+    set(DOXYGEN_MACRO_EXPANSION YES)
+    set(DOXYGEN_EXPAND_ONLY_PREDEF YES)
+    set(DOXYGEN_GENERATE_TODOLIST NO)
+    set(DOXYGEN_PREDEFINED "UNUSED(x)=x" "METHODDEF(x)=static x" "GLOBAL(x)=x")
+    set(DOXYGEN_EXPAND_AS_DEFINED DEFAULT_COMPONENT_ALLOCATOR DEFAULT_SCRIPT_WRAPPER DEFAULT_INTERFACE_WRAPPER DEFAULT_MESSAGE_IMPL MESSAGE INTERFACE COMPONENT GUISTDTYPE)
+    set(DOXYGEN_WARN_LOGFILE doxygen.log)
+
+    doxygen_add_docs(${CMAKE_PROJECT_NAME}
+             ${CMAKE_CURRENT_SOURCE_DIR}/../../source
+             ${CMAKE_CURRENT_SOURCE_DIR}/Main-Page.md
+             ${CMAKE_CURRENT_SOURCE_DIR}/../../LICENSE.md
+            ALL)
+else()
+    message(SEND_ERROR "Make sure Doxygen is installed and usable")
+endif()
@@ -0,0 +1,14 @@
+# Pyrogenesis
+
+The Pyrogenesis Engine is specifically designed for flexibility and ease of modification.
+This document should help all that want to contribute their Work to this Engine.
+
+## Thirdparty
+
+- [Vulkan Memory Allocator](https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/)
+- [tinygettext](https://github.com/tinygettext/tinygettext)
+- [doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css)
+
+## License
+
+[0 A.D. Licensing Details](../../LICENSE.md)
@@ -1,32 +0,0 @@
-PROJECT_NAME           = Pyrogenesis
-PROJECT_NUMBER         = trunk
-
-TAB_SIZE               = 4
-
-INPUT                  = ../../source
-INCLUDE_PATH           = ../../source
-EXAMPLE_PATH           = ../../source
-RECURSIVE              = YES
-EXCLUDE_PATTERNS       = */.svn* */tests/test_*
-EXCLUDE                = ../../source/tools ../../source/i18n/tests2 ../../source/simulation
-
-JAVADOC_AUTOBRIEF      = YES
-
-EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = YES
-EXTRACT_STATIC         = YES
-EXTRACT_ANON_NSPACES   = YES
-
-SHOW_DIRECTORIES       = YES
-STRIP_CODE_COMMENTS    = NO
-GENERATE_LATEX         = NO
-
-MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = YES
-PREDEFINED             = "UNUSED(x)=x" \
-                         "METHODDEF(x)=static x" \
-                         "GLOBAL(x)=x"                 
-EXPAND_AS_DEFINED     += DEFAULT_COMPONENT_ALLOCATOR DEFAULT_SCRIPT_WRAPPER DEFAULT_INTERFACE_WRAPPER DEFAULT_MESSAGE_IMPL
-EXPAND_AS_DEFINED     += MESSAGE INTERFACE COMPONENT GUISTDTYPE
- 
-WARN_LOGFILE           = doxygen.log
@@ -0,0 +1,7 @@
+html {
+    --primary-color: #9A3334;
+    --primary-dark-color: #602021;
+    --primary-light-color: #bf4042;
+    --header-background: var(--primary-color);
+    --header-foreground: #FFFFFF;
+}