Doxygen: Use newer version (#6345)

* readd properties

* use newer doxygen version + print config update diff

* readd config options

* fix config

* revert cache change

* GITHUB md

* graphviz version

* Add doxygen output to .gitignore

.github/workflows/documentation-build.yml

@@ -23,10 +23,31 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v5
 
-      - name: Install Doxygen and Graphviz
+      - name: Install Graphviz
-        run: sudo apt-get install -y doxygen graphviz
+        run: |
+          sudo apt-get install -y graphviz
+          dot -V
+
+      - name: Install Doxygen
+        uses: ssciwr/doxygen-install@v1
+        with:
+          version: "1.14.0"
+
+      - name: Update Doxygen Configuration
+        run: |
+          git diff Doxyfile
+          doxygen -u Doxyfile
+          if git diff --quiet Doxyfile; then
+            echo "::notice::No config changes in Doxyfile detected."
+          else
+            echo "::error::Config changes in Doxyfile detected! Please update the file by running 'doxygen -u Doxyfile'."
+            echo ""
+            git diff --color=always Doxyfile
+            exit 1
+          fi
 
       - name: Generate Documentation
+        if: always()
         run: doxygen Doxyfile
 
       - name: Deploy to cockatrice.github.io

.gitignore

@@ -14,3 +14,4 @@ compile_commands.json
 .cache
 .gdb_history
 cockatrice/resources/config/qtlogging.ini
+docs/

Doxyfile

@@ -1,5 +1,4 @@
 # Doxyfile 1.14.0
-# Doxygen Docs: https://www.doxygen.nl/manual
 
 # This file describes the settings to be used by the documentation system
 # Doxygen (www.doxygen.org) for a project.
@@ -43,7 +42,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "Cockatrice"
+PROJECT_NAME           = Cockatrice
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -55,7 +54,7 @@ PROJECT_NUMBER         = $(COCKATRICE_REF)
 # for a project that appears at the top of each page and should give viewers a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = A cross-platform virtual tabletop for multiplayer card games
+PROJECT_BRIEF          = "A cross-platform virtual tabletop for multiplayer card games"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -64,6 +63,12 @@ PROJECT_BRIEF          = A cross-platform virtual tabletop for multiplayer card
 
 PROJECT_LOGO           = cockatrice/resources/cockatrice.png
 
+# With the PROJECT_ICON tag one can specify an icon that is included in the tabs
+# when the HTML document is shown. Doxygen will copy the logo to the output
+# directory.
+
+PROJECT_ICON           = cockatrice/resources/cockatrice.png
+
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
 # entered, it will be relative to the location where Doxygen was started. If
@@ -374,7 +379,7 @@ TOC_INCLUDE_HEADINGS   = 6
 # The default value is: DOXYGEN.
 # This tag requires that the tag MARKDOWN_SUPPORT is set to YES.
 
-MARKDOWN_ID_STYLE      = DOXYGEN
+MARKDOWN_ID_STYLE      = GITHUB
 
 # When enabled Doxygen tries to link words that correspond to documented
 # classes, or namespaces to their corresponding documentation. Such a link can
@@ -385,6 +390,14 @@ MARKDOWN_ID_STYLE      = DOXYGEN
 
 AUTOLINK_SUPPORT       = YES
 
+# This tag specifies a list of words that, when matching the start of a word in
+# the documentation, will suppress auto links generation, if it is enabled via
+# AUTOLINK_SUPPORT. This list does not affect links explicitly created using \#
+# or the \link or commands.
+# This tag requires that the tag AUTOLINK_SUPPORT is set to YES.
+
+AUTOLINK_IGNORE_WORDS  =
+
 # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
 # to include (a tag file for) the STL sources as input, then you should set this
 # tag to YES in order to let Doxygen match functions declarations and
@@ -486,7 +499,7 @@ TYPEDEF_HIDES_STRUCT   = NO
 # the optimal cache size from a speed point of view.
 # Minimum value: 0, maximum value: 9, default value: 0.
 
-LOOKUP_CACHE_SIZE      = 1
+LOOKUP_CACHE_SIZE      = 0
 
 # The NUM_PROC_THREADS specifies the number of threads Doxygen is allowed to use
 # during processing. When set to 0 Doxygen will based this on the number of
@@ -596,6 +609,14 @@ HIDE_UNDOC_MEMBERS     = NO
 
 HIDE_UNDOC_CLASSES     = NO
 
+# If the HIDE_UNDOC_NAMESPACES tag is set to YES, Doxygen will hide all
+# undocumented namespaces that are normally visible in the namespace hierarchy.
+# If set to NO, these namespaces will be included in the various overviews. This
+# option has no effect if EXTRACT_ALL is enabled.
+# The default value is: YES.
+
+HIDE_UNDOC_NAMESPACES  = YES
+
 # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all friend
 # declarations. If set to NO, these declarations will be included in the
 # documentation.
@@ -830,6 +851,22 @@ LAYOUT_FILE            = doc/doxygen/DoxygenLayout.xml
 
 CITE_BIB_FILES         =
 
+# The EXTERNAL_TOOL_PATH tag can be used to extend the search path (PATH
+# environment variable) so that external tools such as latex and gs can be
+# found.
+# Note: Directories specified with EXTERNAL_TOOL_PATH are added in front of the
+# path already specified by the PATH variable, and are added in the order
+# specified.
+# Note: This option is particularly useful for macOS version 14 (Sonoma) and
+# higher, when running Doxygen from Doxywizard, because in this case any user-
+# defined changes to the PATH are ignored. A typical example on macOS is to set
+# EXTERNAL_TOOL_PATH = /Library/TeX/texbin /usr/local/bin
+# together with the standard path, the full search path used by doxygen when
+# launching external tools will then become
+# PATH=/Library/TeX/texbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+
+EXTERNAL_TOOL_PATH     =
+
 #---------------------------------------------------------------------------
 # Configuration options related to warning and progress messages
 #---------------------------------------------------------------------------
@@ -890,6 +927,14 @@ WARN_NO_PARAMDOC       = NO
 
 WARN_IF_UNDOC_ENUM_VAL = NO
 
+# If WARN_LAYOUT_FILE option is set to YES, Doxygen will warn about issues found
+# while parsing the user defined layout file, such as missing or wrong elements.
+# See also LAYOUT_FILE for details. If set to NO, problems with the layout file
+# will be suppressed.
+# The default value is: YES.
+
+WARN_LAYOUT_FILE       = YES
+
 # If the WARN_AS_ERROR tag is set to YES then Doxygen will immediately stop when
 # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS
 # then Doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but
@@ -986,8 +1031,7 @@ INPUT_FILE_ENCODING    =
 # provided as Doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
 # *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice.
 
-FILE_PATTERNS          = *.c \
+FILE_PATTERNS          = *.cc \
-                         *.cc \
                          *.cxx \
                          *.cxxm \
                          *.cpp \
@@ -1022,7 +1066,11 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which Doxygen is
 # run.
 
-EXCLUDE                = build/ cmake/ vcpkg/ dbconverter/ webclient/
+EXCLUDE                = build/ \
+                         cmake/ \
+                         dbconverter/ \
+                         vcpkg/ \
+                         webclient/
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1038,7 +1086,8 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = .* .*/
+EXCLUDE_PATTERNS       = .* \
+                         .*/
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1135,6 +1184,15 @@ FILTER_SOURCE_PATTERNS =
 
 USE_MDFILE_AS_MAINPAGE =
 
+# If the IMPLICIT_DIR_DOCS tag is set to YES, any README.md file found in sub-
+# directories of the project's root, is used as the documentation for that sub-
+# directory, except when the README.md starts with a \dir, \page or \mainpage
+# command. If set to NO, the README.md file needs to start with an explicit \dir
+# command in order to be used as directory documentation.
+# The default value is: YES.
+
+IMPLICIT_DIR_DOCS      = YES
+
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common
 # extension is to allow longer lines before the automatic comment starts. The
@@ -1231,6 +1289,46 @@ USE_HTAGS              = NO
 
 VERBATIM_HEADERS       = YES
 
+# If the CLANG_ASSISTED_PARSING tag is set to YES then Doxygen will use the
+# clang parser (see:
+# http://clang.llvm.org/) for more accurate parsing at the cost of reduced
+# performance. This can be particularly helpful with template rich C++ code for
+# which Doxygen's built-in parser lacks the necessary type information.
+# Note: The availability of this option depends on whether or not Doxygen was
+# generated with the -Duse_libclang=ON option for CMake.
+# The default value is: NO.
+
+CLANG_ASSISTED_PARSING = NO
+
+# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS
+# tag is set to YES then Doxygen will add the directory of each input to the
+# include path.
+# The default value is: YES.
+# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
+
+CLANG_ADD_INC_PATHS    = YES
+
+# If clang assisted parsing is enabled you can provide the compiler with command
+# line options that you would normally use when invoking the compiler. Note that
+# the include paths will already be set by Doxygen for the files and directories
+# specified with INPUT and INCLUDE_PATH.
+# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
+
+CLANG_OPTIONS          =
+
+# If clang assisted parsing is enabled you can provide the clang parser with the
+# path to the directory containing a file called compile_commands.json. This
+# file is the compilation database (see:
+# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the
+# options used when the source files were built. This is equivalent to
+# specifying the -p option to a clang tool, such as clang-check. These options
+# will then be passed to the parser. Any options specified with CLANG_OPTIONS
+# will be added as well.
+# Note: The availability of this option depends on whether or not Doxygen was
+# generated with the -Duse_libclang=ON option for CMake.
+
+CLANG_DATABASE_PATH    =
+
 #---------------------------------------------------------------------------
 # Configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
@@ -1414,6 +1512,26 @@ HTML_DYNAMIC_SECTIONS  = NO
 
 HTML_CODE_FOLDING      = YES
 
+# If the HTML_COPY_CLIPBOARD tag is set to YES then Doxygen will show an icon in
+# the top right corner of code and text fragments that allows the user to copy
+# its content to the clipboard. Note this only works if supported by the browser
+# and the web page is served via a secure context (see:
+# https://www.w3.org/TR/secure-contexts/), i.e. using the https: or file:
+# protocol.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+HTML_COPY_CLIPBOARD    = YES
+
+# Doxygen stores a couple of settings persistently in the browser (via e.g.
+# cookies). By default these settings apply to all HTML pages generated by
+# Doxygen across all projects. The HTML_PROJECT_COOKIE tag can be used to store
+# the settings under a project specific key, such that the user preferences will
+# be stored separately.
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+HTML_PROJECT_COOKIE    =
+
 # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries
 # shown in the various tree structured indices initially; the user can expand
 # and collapse entries dynamically later on. Doxygen will expand the tree to
@@ -1666,6 +1784,16 @@ DISABLE_INDEX          = YES
 
 GENERATE_TREEVIEW      = YES
 
+# When GENERATE_TREEVIEW is set to YES, the PAGE_OUTLINE_PANEL option determines
+# if an additional navigation panel is shown at the right hand side of the
+# screen, displaying an outline of the contents of the main page, similar to
+# e.g. https://developer.android.com/reference If GENERATE_TREEVIEW is set to
+# NO, this option has no effect.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+PAGE_OUTLINE_PANEL     = YES
+
 # When GENERATE_TREEVIEW is set to YES, the FULL_SIDEBAR option determines if
 # the side bar is limited to only the treeview area (value NO) or if it should
 # extend to the full height of the window (value YES). Setting this to YES gives
@@ -1687,6 +1815,12 @@ FULL_SIDEBAR           = NO
 
 ENUM_VALUES_PER_LINE   = 4
 
+# When the SHOW_ENUM_VALUES tag is set doxygen will show the specified
+# enumeration values besides the enumeration mnemonics.
+# The default value is: NO.
+
+SHOW_ENUM_VALUES       = NO
+
 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used
 # to set the initial width (in pixels) of the frame in which the tree is shown.
 # Minimum value: 0, maximum value: 1500, default value: 250.
@@ -2135,6 +2269,14 @@ RTF_STYLESHEET_FILE    =
 
 RTF_EXTENSIONS_FILE    =
 
+# The RTF_EXTRA_FILES tag can be used to specify one or more extra images or
+# other source files which should be copied to the RTF_OUTPUT output directory.
+# Note that the files will be copied as-is; there are no commands or markers
+# available.
+# This tag requires that the tag GENERATE_RTF is set to YES.
+
+RTF_EXTRA_FILES        =
+
 #---------------------------------------------------------------------------
 # Configuration options related to the man page output
 #---------------------------------------------------------------------------
@@ -2481,7 +2623,7 @@ DOT_COMMON_ATTR        = "fontname=Helvetica,fontsize=10"
 # The default value is: labelfontname=Helvetica,labelfontsize=10.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_EDGE_ATTR  = "labelfontname=Helvetica,labelfontsize=10,arrowhead=open, arrowtail=open, arrowsize=0.5"
+DOT_EDGE_ATTR          = "labelfontname=Helvetica,labelfontsize=10,arrowhead=open, arrowtail=open, arrowsize=0.5"
 
 # DOT_NODE_ATTR is concatenated with DOT_COMMON_ATTR. For view without boxes
 # around nodes set 'shape=plain' or 'shape=plaintext' <a
@@ -2489,7 +2631,7 @@ DOT_EDGE_ATTR  = "labelfontname=Helvetica,labelfontsize=10,arrowhead=open, arrow
 # The default value is: shape=box,height=0.2,width=0.4.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_NODE_ATTR  = "shape=box,height=0.2,width=0.4"
+DOT_NODE_ATTR          = "shape=box,height=0.2,width=0.4"
 
 # You can set the path where dot can find font specified with fontname in
 # DOT_COMMON_ATTR and others dot attributes.
@@ -2558,6 +2700,15 @@ UML_LOOK               = NO
 
 UML_LIMIT_NUM_FIELDS   = 10
 
+# If the UML_LOOK tag is enabled, field labels are shown along the edge between
+# two class nodes. If there are many fields and many nodes the graph may become
+# too cluttered. The UML_MAX_EDGE_LABELS threshold limits the number of items to
+# make the size more manageable. Set this to 0 for no limit.
+# Minimum value: 0, maximum value: 100, default value: 10.
+# This tag requires that the tag UML_LOOK is set to YES.
+
+UML_MAX_EDGE_LABELS    = 10
+
 # If the DOT_UML_DETAILS tag is set to NO, Doxygen will show attributes and
 # methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS
 # tag is set to YES, Doxygen will add type and arguments for attributes and
@@ -2737,6 +2888,12 @@ PLANTUML_CFG_FILE      =
 
 PLANTUML_INCLUDE_PATH  =
 
+# The PLANTUMLFILE_DIRS tag can be used to specify one or more directories that
+# contain PlantUml files that are included in the documentation (see the
+# \plantumlfile command).
+
+PLANTUMLFILE_DIRS      =
+
 # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes
 # that will be shown in the graph. If the number of nodes in a graph becomes
 # larger than this value, Doxygen will truncate the graph, which is visualized

doc/doxygen/DoxygenLayout.xml

@@ -121,6 +121,7 @@
             <enums visible="yes" title=""/>
             <functions visible="yes" title=""/>
             <variables visible="yes" title=""/>
+            <properties visible="yes" title=""/>
             <membergroups visible="yes"/>
         </memberdecl>
         <detaileddescription visible="yes" title=""/>
@@ -132,6 +133,7 @@
             <enums visible="yes" title=""/>
             <functions visible="yes" title=""/>
             <variables visible="yes" title=""/>
+            <properties visible="yes" title=""/>
         </memberdef>
         <authorsection visible="yes"/>
     </namespace>
@@ -167,6 +169,7 @@
             <enums visible="yes" title=""/>
             <functions visible="yes" title=""/>
             <variables visible="yes" title=""/>
+            <properties visible="yes" title=""/>
             <membergroups visible="yes"/>
         </memberdecl>
         <detaileddescription visible="yes" title=""/>
@@ -179,6 +182,7 @@
             <enums visible="yes" title=""/>
             <functions visible="yes" title=""/>
             <variables visible="yes" title=""/>
+            <properties visible="yes" title=""/>
         </memberdef>
         <authorsection/>
     </file>