From f5afea3421ea68899d3064b09184c29f30ce0588 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Thu, 7 Sep 2023 18:28:55 +0200 Subject: [PATCH] Update Doxyfile.in again, now using all defined doxygen tags The process to generate the docs now uses the full Doxyfile as given by `doxygen -u Doxyfile.in` with a specific doxygen version, in this commit version 1.8.14. There's only one addition: 'HTML_COLORSTYLE = TOGGLE' which has been added to doxygen in version 1.9.5. We're using it now to give the user the choice to select a "dark mode" or "light mode" theme if the docs are generated with doxygen 1.9.5 or later. Unknown doxygen tags are now filtered silently and logged in files documentation/Doxyfile_error.log and documentation/Doxybook_error.log, respectively. --- documentation/CMakeLists.txt | 51 ++++--- documentation/Doxyfile.in | 234 ++++++++++++++++----------------- documentation/Makefile | 7 +- documentation/convert_doxyfile | 44 +++++++ 4 files changed, 195 insertions(+), 141 deletions(-) create mode 100755 documentation/convert_doxyfile diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 9405b864a..5cfcb0de6 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -68,15 +68,16 @@ if (GENERATE_DOCS) set (GIT_REVISION "'unkown'") endif() - # find doxygen version + # Find "short" doxygen version if it was built from Git + # Note: this is still needed in CMake 3.12.0 but later CMake versions + # (notably 3.25) remove the Git revision in 'DOXYGEN_VERSION'. + # Todo: Find the "first good" CMake version and remove this redundant + # code once we require this as our minimal version and replace the + # variable DOXYGEN_VERSION_SHORT with DOXYGEN_VERSION below. if (DOXYGEN_FOUND) - # strip trailing git revision if doxygen was built from source string (REGEX REPLACE " .*$" "" DOXYGEN_VERSION_SHORT ${DOXYGEN_VERSION}) - # strip trailing newline - string (REPLACE "\n" "" DOXYGEN_VERSION_SHORT "${DOXYGEN_VERSION_SHORT}") - endif (DOXYGEN_FOUND) # configure copyright.dox (includes current year) @@ -118,31 +119,36 @@ if (OPTION_BUILD_HTML_DOCUMENTATION) set (GENERATE_HTML YES) set (GENERATE_LATEX NO) set (LATEX_HEADER "") + set (DOXYFILE "Doxyfile") + set (LOGFILE "${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}_error.log") # configure Doxygen input file for HTML docs (Doxyfile.in) configure_file ( ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in - ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.in + ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}.in @ONLY ) - # convert Doxyfile to current doxygen version + # convert Doxyfile to used doxygen version - set (LOGFILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_error.log) add_custom_command ( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile - COMMAND ${DOXYGEN_EXECUTABLE} -u -s - < Doxyfile.in > Doxyfile 2> ${LOGFILE} + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE} WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/convert_doxyfile + ${DOXYGEN_EXECUTABLE} + ${DOXYFILE}.in + ${DOXYFILE} + ${LOGFILE} BYPRODUCTS ${LOGFILE} - COMMENT "Converting Doxyfile to doxygen version ${DOXYGEN_VERSION_SHORT}" VERBATIM + COMMENT "Converting ${DOXYFILE} to doxygen version ${DOXYGEN_VERSION_SHORT}" VERBATIM ) # generate HTML documentation add_custom_target (html - COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile + COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE} + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE} WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Generating HTML documentation" VERBATIM ) @@ -162,24 +168,29 @@ if (OPTION_BUILD_PDF_DOCUMENTATION) set (GENERATE_HTML NO) set (GENERATE_LATEX YES) set (LATEX_HEADER "${CMAKE_CURRENT_BINARY_DIR}/fltk-book.tex") + set (DOXYFILE "Doxybook") + set (LOGFILE "${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}_error.log") # configure Doxygen input file for PDF docs (Doxybook.in) configure_file ( ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in - ${CMAKE_CURRENT_BINARY_DIR}/Doxybook.in + ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}.in @ONLY ) # convert Doxybook to current doxygen version - set (LOGFILE ${CMAKE_CURRENT_BINARY_DIR}/Doxybook_error.log) add_custom_command ( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Doxybook - COMMAND ${DOXYGEN_EXECUTABLE} -u -s - < Doxybook.in > Doxybook 2> ${LOGFILE} + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE} WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/convert_doxyfile + ${DOXYGEN_EXECUTABLE} + ${DOXYFILE}.in + ${DOXYFILE} + ${LOGFILE} BYPRODUCTS ${LOGFILE} - COMMENT "Converting Doxybook to doxygen version ${DOXYGEN_VERSION_SHORT}" VERBATIM + COMMENT "Converting ${DOXYFILE} to doxygen version ${DOXYGEN_VERSION_SHORT}" VERBATIM ) # generate LaTeX title fltk-title.tex @@ -198,10 +209,10 @@ if (OPTION_BUILD_PDF_DOCUMENTATION) ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/fltk-title.tex ${CMAKE_CURRENT_BINARY_DIR}/fltk-book.tex - COMMAND ${DOXYGEN_EXECUTABLE} Doxybook + COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE} COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/make_pdf COMMAND cp -f latex/refman.pdf fltk.pdf - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxybook + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE} ${CMAKE_CURRENT_BINARY_DIR}/fltk-title.tex WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Generating PDF documentation" VERBATIM diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in index b3698c71e..bf88783f4 100644 --- a/documentation/Doxyfile.in +++ b/documentation/Doxyfile.in @@ -13,19 +13,6 @@ # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (\" \"). -#--------------------------------------------------------------------------- -# FLTK specific configuration options added *after* Doxygen 1.8.14 -#--------------------------------------------------------------------------- - -# 'HTML_COLORSTYLE': added in Doxygen 1.9.5, default value 'AUTO_LIGHT'. -# We need to set it explicitly to either "LIGHT" or "TOGGLE", otherwise our -# title page may become unreadable for users on a "dark mode" system setup -# unless we also change the background color(s). -# With 'TOGGLE' users can switch between dark and light mode themselves. -# Note: the offending background colors have been removed as of 09/2023. - -HTML_COLORSTYLE = TOGGLE - #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- @@ -89,7 +76,7 @@ CREATE_SUBDIRS = NO # U+3044. # The default value is: NO. -# ALLOW_UNICODE_NAMES = NO +ALLOW_UNICODE_NAMES = NO # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this @@ -248,7 +235,7 @@ ALIASES = # A mapping has the form "name=value". For example adding "class=itcl::class" # will allow you to use the command class in the itcl::class meaning. -# TCL_SUBST = +TCL_SUBST = # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For @@ -295,7 +282,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # Note that for custom extensions you also need to set FILE_PATTERNS otherwise # the files are not read by doxygen. -# EXTENSION_MAPPING = +EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable @@ -305,7 +292,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # case of backward compatibilities issues. # The default value is: YES. -# MARKDOWN_SUPPORT = YES +MARKDOWN_SUPPORT = YES # When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up # to that level are automatically included in the table of contents, even if @@ -314,7 +301,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # Minimum value: 0, maximum value: 99, default value: 0. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -# TOC_INCLUDE_HEADINGS = 0 +TOC_INCLUDE_HEADINGS = 0 # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can @@ -355,8 +342,8 @@ SIP_SUPPORT = NO # type. If this is not the case, or you want to show the methods anyway, you # should set this option to NO. # The default value is: YES. -# 1.5.7 -# IDL_PROPERTY_SUPPORT = YES + +IDL_PROPERTY_SUPPORT = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES then doxygen will reuse the documentation of the first @@ -371,7 +358,7 @@ DISTRIBUTE_GROUP_DOC = NO # is disabled and one has to add nested compounds explicitly via \ingroup. # The default value is: NO. -# GROUP_NESTED_COMPOUNDS = NO +GROUP_NESTED_COMPOUNDS = NO # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that @@ -391,7 +378,7 @@ SUBGROUPING = YES # SEPARATE_MEMBER_PAGES. # The default value is: NO. -# INLINE_GROUPED_CLASSES = NO +INLINE_GROUPED_CLASSES = NO # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions # with only public data fields or simple typedef fields will be shown inline in @@ -401,7 +388,7 @@ SUBGROUPING = YES # Man pages) or section (for LaTeX and RTF). # The default value is: NO. -# INLINE_SIMPLE_STRUCTS = NO +INLINE_SIMPLE_STRUCTS = NO # When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or # enum is documented as struct, union, or enum with the name of the typedef. So @@ -425,7 +412,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 = 0 +LOOKUP_CACHE_SIZE = 0 #--------------------------------------------------------------------------- # Build related configuration options @@ -451,7 +438,7 @@ EXTRACT_PRIVATE = NO # scope will be included in the documentation. # The default value is: NO. -# EXTRACT_PACKAGE = NO +EXTRACT_PACKAGE = NO # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. @@ -542,7 +529,7 @@ HIDE_SCOPE_NAMES = NO # YES the compound reference will be hidden. # The default value is: NO. -# HIDE_COMPOUND_REFERENCE= NO +HIDE_COMPOUND_REFERENCE= NO # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. @@ -555,13 +542,13 @@ SHOW_INCLUDE_FILES = YES # which file to include in order to use the member. # The default value is: NO. -# SHOW_GROUPED_MEMB_INC = NO +SHOW_GROUPED_MEMB_INC = NO # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. -# FORCE_LOCAL_INCLUDES = NO +FORCE_LOCAL_INCLUDES = NO # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. @@ -594,7 +581,7 @@ SORT_BRIEF_DOCS = YES # detailed member documentation. # The default value is: NO. -# SORT_MEMBERS_CTORS_1ST = NO +SORT_MEMBERS_CTORS_1ST = NO # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will @@ -621,7 +608,7 @@ SORT_BY_SCOPE_NAME = NO # accept a match between prototype and implementation in such cases. # The default value is: NO. -# STRICT_PROTO_MATCHING = NO +STRICT_PROTO_MATCHING = NO # The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo # list. This list is created by putting \todo commands in the documentation. @@ -676,15 +663,15 @@ SHOW_USED_FILES = YES # will remove the Files entry from the Quick Index and from the Folder Tree View # (if specified). # The default value is: YES. -# 1.5.7 -# SHOW_FILES = YES + +SHOW_FILES = YES # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces # page. This will remove the Namespaces entry from the Quick Index and from the # Folder Tree View (if specified). # The default value is: YES. -# 1.5.7 -# SHOW_NAMESPACES = YES + +SHOW_NAMESPACES = YES # The FILE_VERSION_FILTER tag can be used to specify a program or script that # doxygen should invoke to get the current version for each file (typically from @@ -706,8 +693,8 @@ FILE_VERSION_FILTER = # Note that if you run doxygen from a directory containing a file called # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -# 1.5.7 -# LAYOUT_FILE = + +LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -717,7 +704,7 @@ FILE_VERSION_FILTER = # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. -# CITE_BIB_FILES = +CITE_BIB_FILES = #--------------------------------------------------------------------------- # Configuration options related to warning and progress messages @@ -766,7 +753,7 @@ WARN_NO_PARAMDOC = NO # a warning is encountered. # The default value is: NO. -# WARN_AS_ERROR = NO +WARN_AS_ERROR = NO # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which @@ -978,14 +965,14 @@ FILTER_SOURCE_FILES = NO # *.ext= (so without naming a filter). # This tag requires that the tag FILTER_SOURCE_FILES is set to YES. -# FILTER_SOURCE_PATTERNS = +FILTER_SOURCE_PATTERNS = # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that # is part of the input, its contents will be placed on the main page # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -# USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -1041,7 +1028,7 @@ REFERENCES_LINK_SOURCE = YES # The default value is: YES. # This tag requires that the tag SOURCE_BROWSER is set to YES. -# SOURCE_TOOLTIPS = YES +SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in @@ -1082,14 +1069,14 @@ VERBATIM_HEADERS = YES # classes, structs, unions or interfaces. # The default value is: YES. -# ALPHABETICAL_INDEX = YES +ALPHABETICAL_INDEX = YES # The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in # which the alphabetical index list will be split. # Minimum value: 1, maximum value: 20, default value: 5. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. -# deprecated: -# COLS_IN_ALPHA_INDEX = 5 + +COLS_IN_ALPHA_INDEX = 5 # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag @@ -1178,7 +1165,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1188,7 +1175,22 @@ HTML_STYLESHEET = # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_EXTRA_FILES = +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output +# should be rendered with a dark or light theme. +# Possible values are: LIGHT always generate light mode output, DARK always +# generate dark mode output, AUTO_LIGHT automatically set the mode according to +# the user preference, use light mode if no preference is set (the default), +# AUTO_DARK automatically set the mode according to the user preference, use +# dark mode if no preference is set and TOGGLE allow to user to switch between +# light and dark mode via a button. +# The default value is: AUTO_LIGHT. +# This tag requires that the tag GENERATE_HTML is set to YES. + +# Note: since doxygen 1.9.5 + +HTML_COLORSTYLE = TOGGLE # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to @@ -1199,7 +1201,7 @@ HTML_STYLESHEET = # Minimum value: 0, maximum value: 359, default value: 220. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_HUE = 220 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors # in the HTML output. For a value of 0 the output will use grayscales only. A @@ -1207,7 +1209,7 @@ HTML_STYLESHEET = # Minimum value: 0, maximum value: 255, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_SAT = 100 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the # luminance component of the colors in the HTML output. Values below 100 @@ -1218,7 +1220,7 @@ HTML_STYLESHEET = # Minimum value: 40, maximum value: 240, default value: 80. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_COLORSTYLE_GAMMA = 80 +HTML_COLORSTYLE_GAMMA = 80 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting this @@ -1227,7 +1229,7 @@ HTML_STYLESHEET = # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_TIMESTAMP = NO +HTML_TIMESTAMP = NO # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that @@ -1238,7 +1240,7 @@ HTML_STYLESHEET = # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_MENUS = YES # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the @@ -1259,7 +1261,7 @@ HTML_DYNAMIC_SECTIONS = NO # Minimum value: 0, maximum value: 9999, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_INDEX_NUM_ENTRIES = 100 +HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development @@ -1297,13 +1299,13 @@ DOCSET_BUNDLE_ID = org.doxygen.Project # The default value is: org.doxygen.Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. -# DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_ID = org.doxygen.Publisher # The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. # The default value is: Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. -# DOCSET_PUBLISHER_NAME = Publisher +DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The @@ -1348,8 +1350,8 @@ GENERATE_CHI = NO # The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) # and project file content. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. -# 1.5.7 -# CHM_INDEX_ENCODING = + +CHM_INDEX_ENCODING = # The BINARY_TOC flag controls whether a binary table of contents is generated # (YES) or a normal table of contents (NO) in the .chm file. Furthermore it @@ -1372,59 +1374,59 @@ TOC_EXPAND = NO # (.qch) of the generated HTML documentation. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -# 1.5.7 -# GENERATE_QHP = NO + +GENERATE_QHP = NO # If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify # the file name of the resulting .qch file. The path specified is relative to # the HTML output folder. # This tag requires that the tag GENERATE_QHP is set to YES. -# 1.5.7 -# QCH_FILE = + +QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace # (see: http://doc.qt.io/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. -# 1.5.7 -# QHP_NAMESPACE = org.doxygen.Project + +QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual # Folders (see: http://doc.qt.io/qt-4.8/qthelpproject.html#virtual-folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. -# 1.5.7 -# QHP_VIRTUAL_FOLDER = doc + +QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom # Filters (see: http://doc.qt.io/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. -# QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom # Filters (see: http://doc.qt.io/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. -# QHP_CUST_FILTER_ATTRS = +QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: # http://doc.qt.io/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. -# QHP_SECT_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = # The QHG_LOCATION tag can be used to specify the location of Qt's # qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the # generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. -# 1.5.7 -# QHG_LOCATION = + +QHG_LOCATION = # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be # generated, together with the HTML files, they form an Eclipse help plugin. To @@ -1436,7 +1438,7 @@ TOC_EXPAND = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -# GENERATE_ECLIPSEHELP = NO +GENERATE_ECLIPSEHELP = NO # A unique identifier for the Eclipse help plugin. When installing the plugin # the directory name containing the HTML and XML files should also have this @@ -1444,7 +1446,7 @@ TOC_EXPAND = NO # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. -# ECLIPSE_DOC_ID = org.doxygen.Project +ECLIPSE_DOC_ID = org.doxygen.Project # If you want full control over the layout of the generated HTML pages it might # be necessary to disable the index and replace it with your own. The @@ -1496,7 +1498,7 @@ TREEVIEW_WIDTH = 250 # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -# EXT_LINKS_IN_WINDOW = NO +EXT_LINKS_IN_WINDOW = NO # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful @@ -1504,8 +1506,8 @@ TREEVIEW_WIDTH = 250 # output directory to force them to be regenerated. # Minimum value: 8, maximum value: 50, default value: 10. # This tag requires that the tag GENERATE_HTML is set to YES. -# 1.5.7 -# FORMULA_FONTSIZE = 10 + +FORMULA_FONTSIZE = 10 # Use the FORMULA_TRANSPARENT tag to determine whether or not the images # generated for formulas are transparent PNGs. Transparent PNGs are not @@ -1516,7 +1518,7 @@ TREEVIEW_WIDTH = 250 # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -# FORMULA_TRANSPARENT = YES +FORMULA_TRANSPARENT = YES # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # https://www.mathjax.org) which uses client side Javascript for the rendering @@ -1527,7 +1529,7 @@ TREEVIEW_WIDTH = 250 # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -# USE_MATHJAX = NO +USE_MATHJAX = NO # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: @@ -1537,7 +1539,7 @@ TREEVIEW_WIDTH = 250 # The default value is: HTML-CSS. # This tag requires that the tag USE_MATHJAX is set to YES. -# MATHJAX_FORMAT = HTML-CSS +MATHJAX_FORMAT = HTML-CSS # When MathJax is enabled you need to specify the location relative to the HTML # output directory using the MATHJAX_RELPATH option. The destination directory @@ -1550,14 +1552,14 @@ TREEVIEW_WIDTH = 250 # The default value is: https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/. # This tag requires that the tag USE_MATHJAX is set to YES. -# MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/ +MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/ # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols # This tag requires that the tag USE_MATHJAX is set to YES. -# MATHJAX_EXTENSIONS = +MATHJAX_EXTENSIONS = # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site @@ -1565,7 +1567,7 @@ TREEVIEW_WIDTH = 250 # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. -# MATHJAX_CODEFILE = +MATHJAX_CODEFILE = # When the SEARCHENGINE tag is enabled doxygen will generate a search box for # the HTML output. The underlying search engine uses javascript and DHTML and @@ -1586,7 +1588,6 @@ TREEVIEW_WIDTH = 250 # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -# This tag was previously set to "NO". Testing YES (Sep 07, 2023). SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be @@ -1599,7 +1600,7 @@ SEARCHENGINE = YES # The default value is: NO. # This tag requires that the tag SEARCHENGINE is set to YES. -# SERVER_BASED_SEARCH = NO +SERVER_BASED_SEARCH = NO # When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP # script for searching. Instead the search results are written to an XML file @@ -1615,7 +1616,7 @@ SEARCHENGINE = YES # The default value is: NO. # This tag requires that the tag SEARCHENGINE is set to YES. -# EXTERNAL_SEARCH = NO +EXTERNAL_SEARCH = NO # The SEARCHENGINE_URL should point to a search engine hosted by a web server # which will return the search results when EXTERNAL_SEARCH is enabled. @@ -1626,7 +1627,7 @@ SEARCHENGINE = YES # Searching" for details. # This tag requires that the tag SEARCHENGINE is set to YES. -# SEARCHENGINE_URL = +SEARCHENGINE_URL = # When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed # search data is written to a file for indexing by an external tool. With the @@ -1634,7 +1635,7 @@ SEARCHENGINE = YES # The default file is: searchdata.xml. # This tag requires that the tag SEARCHENGINE is set to YES. -# SEARCHDATA_FILE = searchdata.xml +SEARCHDATA_FILE = searchdata.xml # When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the # EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is @@ -1642,7 +1643,7 @@ SEARCHENGINE = YES # projects and redirect the results back to the right project. # This tag requires that the tag SEARCHENGINE is set to YES. -# EXTERNAL_SEARCH_ID = +EXTERNAL_SEARCH_ID = # The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen # projects other than the one defined by this configuration file, but that are @@ -1652,7 +1653,7 @@ SEARCHENGINE = YES # EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ... # This tag requires that the tag SEARCHENGINE is set to YES. -# EXTRA_SEARCH_MAPPINGS = +EXTRA_SEARCH_MAPPINGS = #--------------------------------------------------------------------------- # Configuration options related to the LaTeX output @@ -1743,7 +1744,7 @@ LATEX_HEADER = @LATEX_HEADER@ # Note: Only use a user-defined footer if you know what you are doing! # This tag requires that the tag GENERATE_LATEX is set to YES. -# LATEX_FOOTER = +LATEX_FOOTER = # The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined # LaTeX style sheets that are included after the standard style sheets created @@ -1754,7 +1755,7 @@ LATEX_HEADER = @LATEX_HEADER@ # list). # This tag requires that the tag GENERATE_LATEX is set to YES. -# LATEX_EXTRA_STYLESHEET = +LATEX_EXTRA_STYLESHEET = # The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the LATEX_OUTPUT output @@ -1762,7 +1763,7 @@ LATEX_HEADER = @LATEX_HEADER@ # markers available. # This tag requires that the tag GENERATE_LATEX is set to YES. -# LATEX_EXTRA_FILES = +LATEX_EXTRA_FILES = # If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is # prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will @@ -1805,7 +1806,7 @@ LATEX_HIDE_INDICES = NO # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. -# LATEX_SOURCE_CODE = NO +LATEX_SOURCE_CODE = NO # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See @@ -1813,7 +1814,7 @@ LATEX_HIDE_INDICES = NO # The default value is: plain. # This tag requires that the tag GENERATE_LATEX is set to YES. -# LATEX_BIB_STYLE = plain +LATEX_BIB_STYLE = plain # If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated # page will contain the date and time when the page was generated. Setting this @@ -1821,7 +1822,7 @@ LATEX_HIDE_INDICES = NO # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. -# LATEX_TIMESTAMP = NO +LATEX_TIMESTAMP = NO #--------------------------------------------------------------------------- # Configuration options related to the RTF output @@ -1887,7 +1888,7 @@ RTF_EXTENSIONS_FILE = # The default value is: NO. # This tag requires that the tag GENERATE_RTF is set to YES. -# RTF_SOURCE_CODE = NO +RTF_SOURCE_CODE = NO #--------------------------------------------------------------------------- # Configuration options related to the man page output @@ -1922,7 +1923,7 @@ MAN_EXTENSION = .3 # MAN_EXTENSION with the initial . removed. # This tag requires that the tag GENERATE_MAN is set to YES. -# MAN_SUBDIR = +MAN_SUBDIR = # If the MAN_LINKS tag is set to YES and doxygen generates man output, then it # will generate one additional man file for each entity documented in the real @@ -1958,7 +1959,7 @@ XML_OUTPUT = xml # The default value is: YES. # This tag requires that the tag GENERATE_XML is set to YES. -# XML_PROGRAMLISTING = YES +XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output @@ -1968,7 +1969,7 @@ XML_OUTPUT = xml # that can be used to generate PDF. # The default value is: NO. -# GENERATE_DOCBOOK = NO +GENERATE_DOCBOOK = NO # The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be put in @@ -1976,7 +1977,7 @@ XML_OUTPUT = xml # The default directory is: docbook. # This tag requires that the tag GENERATE_DOCBOOK is set to YES. -# DOCBOOK_OUTPUT = docbook +DOCBOOK_OUTPUT = docbook # If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the # program listings (including syntax highlighting and cross-referencing @@ -1985,7 +1986,7 @@ XML_OUTPUT = xml # The default value is: NO. # This tag requires that the tag GENERATE_DOCBOOK is set to YES. -# DOCBOOK_PROGRAMLISTING = NO +DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output @@ -2165,14 +2166,13 @@ EXTERNAL_GROUPS = YES # be listed. # The default value is: YES. -# EXTERNAL_PAGES = YES +EXTERNAL_PAGES = YES # The PERL_PATH should be the absolute path and name of the perl script # interpreter (i.e. the result of 'which perl'). # The default file (with absolute path) is: /usr/bin/perl. -# obsolete as of Doxygen 1.8.16 (use default for older versions) -# PERL_PATH = /usr/bin/perl +PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- # Configuration options related to the dot tool @@ -2185,8 +2185,7 @@ EXTERNAL_GROUPS = YES # powerful graphs. # The default value is: YES. -# obsolete as of Doxygen 1.9.3, using default (YES) anyway -# CLASS_DIAGRAMS = YES +CLASS_DIAGRAMS = YES # You can define message sequence charts within doxygen comments using the \msc # command. Doxygen will then run the mscgen tool (see: @@ -2195,14 +2194,14 @@ EXTERNAL_GROUPS = YES # the mscgen tool resides. If left empty the tool is assumed to be found in the # default search path. -# MSCGEN_PATH = +MSCGEN_PATH = # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. # If left empty dia is assumed to be found in the default search path. -# DIA_PATH = +DIA_PATH = # If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. @@ -2227,7 +2226,7 @@ HAVE_DOT = NO # Minimum value: 0, maximum value: 32, default value: 0. # This tag requires that the tag HAVE_DOT is set to YES. -# DOT_NUM_THREADS = 0 +DOT_NUM_THREADS = 0 # When you want a differently looking font in the dot files that doxygen # generates you can specify the font name using DOT_FONTNAME. You need to make @@ -2237,14 +2236,14 @@ HAVE_DOT = NO # The default value is: Helvetica. # This tag requires that the tag HAVE_DOT is set to YES. -# DOT_FONTNAME = Helvetica +DOT_FONTNAME = Helvetica # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of # dot graphs. # Minimum value: 4, maximum value: 24, default value: 10. # This tag requires that the tag HAVE_DOT is set to YES. -# DOT_FONTSIZE = 10 +DOT_FONTSIZE = 10 # By default doxygen will tell dot to use the default font as specified with # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set @@ -2296,7 +2295,7 @@ UML_LOOK = NO # Minimum value: 0, maximum value: 100, default value: 10. # This tag requires that the tag HAVE_DOT is set to YES. -# UML_LIMIT_NUM_FIELDS = 10 +UML_LIMIT_NUM_FIELDS = 10 # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and # collaboration graphs will show the relations between templates and their @@ -2389,7 +2388,7 @@ DOT_IMAGE_FORMAT = png # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -# INTERACTIVE_SVG = NO +INTERACTIVE_SVG = NO # The DOT_PATH tag can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. @@ -2408,13 +2407,13 @@ DOTFILE_DIRS = # contain msc files that are included in the documentation (see the \mscfile # command). -# MSCFILE_DIRS = +MSCFILE_DIRS = # The DIAFILE_DIRS tag can be used to specify one or more directories that # contain dia files that are included in the documentation (see the \diafile # command). -# DIAFILE_DIRS = +DIAFILE_DIRS = # When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the # path where java can find the plantuml.jar file. If left blank, it is assumed @@ -2422,17 +2421,17 @@ DOTFILE_DIRS = # generate a warning when it encounters a \startuml command in this case and # will not generate output for the diagram. -# PLANTUML_JAR_PATH = +PLANTUML_JAR_PATH = # When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a # configuration file for plantuml. -# PLANTUML_CFG_FILE = +PLANTUML_CFG_FILE = # When using plantuml, the specified paths are searched for files specified by # the !include statement in a plantuml block. -# PLANTUML_INCLUDE_PATH = +PLANTUML_INCLUDE_PATH = # 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 @@ -2468,8 +2467,7 @@ MAX_DOT_GRAPH_DEPTH = 0 # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -# obsolete as of Doxygen 1.9.5, using default (NO) anyway -# DOT_TRANSPARENT = NO +DOT_TRANSPARENT = NO # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This diff --git a/documentation/Makefile b/documentation/Makefile index 559b42719..c75dd567c 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -149,7 +149,7 @@ uninstall-linux uninstall-osx: Doxyfile: Doxyfile.in generated.dox copyright.dox echo "Generating Doxyfile ..." - $(DOXYDOC) -u -s - < $< 2>Doxyfile_error.log | \ + ./convert_doxyfile $(DOXYDOC) $< $@ Doxyfile_error.log sed -e's,@FLTK_VERSION@,$(FLTK_VERSION),' \ -e's,@GENERATE_HTML@,YES,' \ -e's,@GENERATE_LATEX@,NO,' \ @@ -158,10 +158,11 @@ Doxyfile: Doxyfile.in generated.dox copyright.dox -e's,@CMAKE_CURRENT_SOURCE_DIR@,.,' \ -e's,@CMAKE_CURRENT_BINARY_DIR@,,' \ -e's,@FLTK_SOURCE_DIR@,..,' \ - > $@ + -i $@ Doxybook: Doxyfile.in generated.dox copyright.dox echo "Generating Doxybook ..." + ./convert_doxyfile $(DOXYDOC) $< $@ Doxybook_error.log $(DOXYDOC) -u -s - < $< 2>Doxybook_error.log | \ sed -e's,@FLTK_VERSION@,$(FLTK_VERSION),' \ -e's,@GENERATE_HTML@,NO,' \ @@ -171,7 +172,7 @@ Doxybook: Doxyfile.in generated.dox copyright.dox -e's,@CMAKE_CURRENT_SOURCE_DIR@,.,' \ -e's,@CMAKE_CURRENT_BINARY_DIR@,,' \ -e's,@FLTK_SOURCE_DIR@,..,' \ - > $@ + -i $@ # The HTML files are generated using doxygen, and this needs # an installed doxygen version and may take some time, so this target diff --git a/documentation/convert_doxyfile b/documentation/convert_doxyfile new file mode 100755 index 000000000..57c3c28a6 --- /dev/null +++ b/documentation/convert_doxyfile @@ -0,0 +1,44 @@ +#!/bin/sh +# +# Convert 'Doxyfile.in' to 'Doxyfile' or 'Doxybook' for doxygen docs +# +# Usage: +# +# $ sh convert_doxyfile doxygen_path input output logfile +# +# where +# - 'doxygen_path' is the full path to the doxygen executable or just +# 'doxygen' if this is in the user's PATH. If the full path is used +# an arbitrary doxygen executable and thus doxygen version can be used. +# - 'input' is the file 'Doxyfile.in' stored in Git or any other file. +# - 'output' is the generated doxygen file, usually either 'Doxyfile' +# or 'Doxybook' which will be used subsequently to generate the +# HTML or PDF docs, respectively. +# +# Doxygen warnings and errors are stored in 'logfile' for review. +# +#======================================================================= +# This script requires a posix shell and uses the following commands: +# 'echo', 'date', and (obviously) doxygen. +#======================================================================= + +# doxygen command, input and output file names + +DOXYGEN="$1" + INFILE="$2" +OUTFILE="$3" +LOGFILE="$4" + +# get doxygen version + +VERSION=$($DOXYGEN --version) + +# write info header to LOGFILE + +echo "$OUTFILE created by doxygen version $VERSION" > $LOGFILE +echo " at `date`" >> $LOGFILE +echo "" >> $LOGFILE + +# convert doxygen file and append errors and warnings to LOGFILE + +${DOXYGEN} -u -s - < $INFILE > $OUTFILE 2>> $LOGFILE