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

.gitignore

@@ -49,6 +49,9 @@ build/premake/.already-built
 build/premake/.gccmachine.tmp
 build/premake/.gccver.tmp
 
+# Docs build folder
+docs/doxygen/output/
+
 # Build files (cpp)
 *.a
 *.dylib

LICENSE.md

@@ -0,0 +1,104 @@
+# 0 A.D. Licensing Details
+
+0 A.D. and the Pyrogenesis engine are released as free and open source: you can freely use, copy,
+modify and distribute the game's source code and data files, as long as you include
+attribution to Wildfire Games and let anyone freely modify and distribute any
+of your own modifications to the game's files.
+
+The distribution includes several different types of files, and a number of
+third-party components. The details are described here, based on the directory
+structure. For any file, see the longest path name below which is a prefix of
+the file's path.
+
+If you have a question about, or can provide any information on missing or wrong licensing details,
+please inform Wildfire Games at webmaster at wildfiregames dot com.
+
+## Other Licenses based on the Directory Structure
+
+- binaries/data/
+  - GPL version 2 (or later) - see license_gpl-2.0.txt
+
+- binaries/data/mods/*/art
+- binaries/data/mods/*/audio
+  - Creative Commons Attribution-Share Alike 3.0 - see
+        http://creativecommons.org/licenses/by-sa/3.0/
+        and also see LICENSE.txt within those directories
+
+- binaries/data/mods/*/maps/
+  - see LICENSE.txt within those directories
+
+- binaries/data/mods/public/shaders/glsl/fxaa.fs
+  - BSD
+
+- binaries/data/mods/public/shaders/glsl/cas.fs
+  - MIT
+
+- binaries/system/
+  - Various (unspecified)
+
+- binaries/system/dbghelp.dll
+  - Proprietary - see license_dbghelp.txt for restrictions you must agree to
+      before distributing this particular file
+
+- build/
+  - Various (unspecified)
+
+- build/arclint/
+  - GPL version 2 (or later) - see license_gpl-2.0.txt
+
+- build/arclint/pyrolint/
+  - Apache version 2 - see license_apache2.txt within that directory
+
+- build/premake/premake5/
+  - BSD
+
+- build/premake/*.lua
+  - MIT - see license_mit.txt
+
+- docs/
+  - Various (unspecified)
+
+- libraries/
+  - Various - see LICENSE.txt within that directory
+
+- source/
+  - GPL version 2 (or later) - see license_gpl-2.0.txt
+
+- source/lib/
+  - MIT - see license_mit.txt
+
+- source/scriptinterface/third_party/
+  - MPL 2.0
+
+- source/third_party/encryption/
+  - GPL version 2 (or later)
+  - ISC (pkcs5_pbkdf2.cpp)
+  - MIT (pkcs5_pbkdf2.h) - see license_mit.txt
+
+- source/third-party/jsonspirit/
+  - MIT - see license_mit.txt
+
+- source/third_party/mikktspace/
+  - zlib
+
+- source/third_party/mongoose/
+  - MIT - see license_mit.txt
+
+- source/third_party/tinygettext/
+  - zlib
+
+- source/third-party/vma/
+  - MIT - see LICENSE.txt within that directory
+
+- source/tools/
+  - Various - see LICENSE.txt within that directory
+
+- source/tools/atlas/
+  - GPL version 2 (or later) - see license_gpl-2.0.txt
+
+- binaries/data/mods/public/gui/prelobby/common/terms/  
+  binaries/data/mods/public/gui/userreport/Terms_and_Conditions.txt  
+  binaries/data/mods/mod/gui/modio/Disclaimer.txt
+  - Redistributing modified Terms and Conditions of online services may be within the licensing,
+    but may not change the legality or enforceability of the terms of the service provider.
+    It may be against the terms of the service provider to use online services with modified terms.

LICENSE.txt

@@ -1,103 +0,0 @@
- 0 A.D. Licensing Details
-==========================
-
-0 A.D. and the Pyrogenesis engine are released as free and open source: you can freely use, copy, modify and
-distribute the game's source code and data files, as long as you include
-attribution to Wildfire Games and let anyone freely modify and distribute any
-of your own modifications to the game's files.
-
-The distribution includes several different types of files, and a number of
-third-party components. The details are described here, based on the directory
-structure. For any file, see the longest path name below which is a prefix of
-the file's path.
-
-If you have a question about, or can provide any information on missing or wrong licensing details,
-please inform Wildfire Games at webmaster at wildfiregames dot com.
-
-  binaries/data/
-    GPL version 2 (or later) - see license_gpl-2.0.txt
-
-  binaries/data/mods/*/art
-  binaries/data/mods/*/audio
-    Creative Commons Attribution-Share Alike 3.0 - see
-    http://creativecommons.org/licenses/by-sa/3.0/
-    and also see LICENSE.txt within those directories
-
-  binaries/data/mods/*/maps/
-  see LICENSE.txt within those directories
-
-  binaries/data/mods/public/shaders/glsl/fxaa.fs
-    BSD
-
-  binaries/data/mods/public/shaders/glsl/cas.fs
-    MIT
-
-  binaries/system/
-    Various (unspecified)
-
-  binaries/system/dbghelp.dll
-    Proprietary - see license_dbghelp.txt for restrictions you must agree to
-    before distributing this particular file
-
-  build/
-    Various (unspecified)
-
-  build/arclint/
-    GPL version 2 (or later) - see license_gpl-2.0.txt
-
-  build/arclint/pyrolint/
-    Apache version 2 - see license_apache2.txt within that directory
-
-  build/premake/premake5/
-    BSD
-
-  build/premake/*.lua
-    MIT - see license_mit.txt
-
-  docs/
-    Various (unspecified)
-
-  libraries/
-    Various - see LICENSE.txt within that directory
-
-  source/
-    GPL version 2 (or later) - see license_gpl-2.0.txt
-
-  source/lib/
-    MIT - see license_mit.txt
-
-  source/scriptinterface/third_party/
-    MPL 2.0
-
-  source/third_party/encryption/
-    GPL version 2 (or later)
-    ISC (pkcs5_pbkdf2.cpp)
-    MIT (pkcs5_pbkdf2.h) - see license_mit.txt
-
-  source/third-party/jsonspirit/
-    MIT - see license_mit.txt
-
-  source/third_party/mikktspace/
-    zlib
-
-  source/third_party/mongoose/
-    MIT - see license_mit.txt
-
-  source/third_party/tinygettext/
-    zlib
-
-  source/third-party/vma/
-    MIT - see LICENSE.txt within that directory
-
-  source/tools/
-    Various - see LICENSE.txt within that directory
-
-  source/tools/atlas/
-    GPL version 2 (or later) - see license_gpl-2.0.txt
-
-  binaries/data/mods/public/gui/prelobby/common/terms/
-  binaries/data/mods/public/gui/userreport/Terms_and_Conditions.txt
-  binaries/data/mods/mod/gui/modio/Disclaimer.txt
-    Redistributing modified Terms and Conditions of online services may be within the licensing,
-    but may not change the legality or enforceability of the terms of the service provider.
-    It may be against the terms of the service provider to use online services with modified terms.

build/jenkins/pipelines/technical-docs.Jenkinsfile

@@ -36,7 +36,7 @@ pipeline {
 
 		stage("Engine docs") {
 			steps {
-				sh "cd docs/doxygen/ && doxygen config"
+				sh "cd docs/doxygen/ && cmake -S . -B build-docs && cmake --build build-docs"
 			}
 		}
 
@@ -59,7 +59,7 @@ pipeline {
 			steps {
 				sshPublisher alwaysPublishFromMaster: true, failOnError: true, publishers: [
 					sshPublisherDesc(configName: 'docs.wildfiregames.com', transfers: [
-						sshTransfer(sourceFiles: 'docs/doxygen/html/**', removePrefix: 'docs/doxygen/html', remoteDirectory: 'pyrogenesis'),
+						sshTransfer(sourceFiles: 'docs/doxygen/output/html/**', removePrefix: 'docs/doxygen/output/html/', remoteDirectory: 'pyrogenesis'),
 						sshTransfer(sourceFiles: 'source/tools/entdocs/nightly.html', removePrefix: 'source/tools/entdocs', remoteDirectory: 'entity-docs'),
 						sshTransfer(sourceFiles: 'source/tools/templatesanalyzer/index.html', removePrefix: 'source/tools/templatesanalyzer', remoteDirectory: 'templatesanalyzer'),
 					]

docs/README.md

@@ -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.

docs/README.txt

@@ -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/

docs/doxygen/CMakeLists.txt

@@ -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()

docs/doxygen/Main-Page.md

@@ -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)

docs/doxygen/config

@@ -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

docs/doxygen/style.css

@@ -0,0 +1,7 @@
+html {
+    --primary-color: #9A3334;
+    --primary-dark-color: #602021;
+    --primary-light-color: #bf4042;
+    --header-background: var(--primary-color);
+    --header-foreground: #FFFFFF;
+}