doxygen.cmake

# Copyright (C) 2008-2025 LAAS-CNRS, JRL AIST-CNRS, INRIA.
#
# This program is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free Software
# Foundation, either version 3 of the License, or (at your option) any later
# version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
# details.
#
# You should have received a copy of the GNU General Public License along with
# this program.  If not, see <http://www.gnu.org/licenses/>.

# .rst: .. ifmode:: user
#
# By default, Doxygen_, if found, is used to generate a HTML documentation of
# the code. You can configure it as follows:
#
# * Many Doxygen options can be configured from CMake itself. E.g. Doxygen
#   option `PROJECT_NAME` can be set using CMake variable
#   `DOXYGEN_PROJECT_NAME`.
#
# * If present, the file *doc/Doxyfile.extra.in* will be configured and append
#   to the above mentionned configuration file.
#
# For a good documentation of the available options, see either `local
# documentation <file:///usr/share/doc/doxygen/html/config.html>`_ provided by
# package *doxygen-doc* or the `online version
# <http://www.doxygen.nl/manual/config.html>`_.
#
# .. variable:: INSTALL_DOCUMENTATION
#
# whether the documentation should be installed. Turning this to OFF does not
# prevent the documentation generation.
#
# .. variable:: BUILD_DOCUMENTATION
#
# This variable controls cmake searches for Doxygen and if the documentation is
# be generated.
#
# .. _Doxygen: http://www.doxygen.nl

# .rst: .. ifmode:: internal
#
# .. command:: _SETUP_DOXYGEN_DEFAULT_OPTIONS
#
# Set default options for doxygen configuration when the user didn't specify
# those options already. To add doxygen configuration option, the easiest is
#
# * `doxygen -s -g Doxyfile.tmp`
# * `awk -f doxyfile.awk doxygen`
#
# :param configfile: the output file
macro(_SETUP_DOXYGEN_CONFIG_FILE configfile)
  file(WRITE ${configfile} "# Generated by cmake/doxygen.cmake\n")
  foreach(
    option
    # This list was generated using doxygen -s -g Doxyfile.tmp awk -f
    # doxyfile.awk doxygen Doxyfile 1.8.18
    # ---------------------------------------------------------------------------
    # Project related configuration options
    # ---------------------------------------------------------------------------
    DOXYFILE_ENCODING
    PROJECT_NAME
    PROJECT_NUMBER
    PROJECT_BRIEF
    PROJECT_LOGO
    OUTPUT_DIRECTORY
    CREATE_SUBDIRS
    ALLOW_UNICODE_NAMES
    OUTPUT_LANGUAGE
    OUTPUT_TEXT_DIRECTION
    BRIEF_MEMBER_DESC
    REPEAT_BRIEF
    ABBREVIATE_BRIEF
    ALWAYS_DETAILED_SEC
    INLINE_INHERITED_MEMB
    FULL_PATH_NAMES
    STRIP_FROM_PATH
    STRIP_FROM_INC_PATH
    SHORT_NAMES
    JAVADOC_AUTOBRIEF
    JAVADOC_BANNER
    QT_AUTOBRIEF
    MULTILINE_CPP_IS_BRIEF
    INHERIT_DOCS
    SEPARATE_MEMBER_PAGES
    TAB_SIZE
    ALIASES
    TCL_SUBST
    OPTIMIZE_OUTPUT_FOR_C
    OPTIMIZE_OUTPUT_JAVA
    OPTIMIZE_FOR_FORTRAN
    OPTIMIZE_OUTPUT_VHDL
    OPTIMIZE_OUTPUT_SLICE
    EXTENSION_MAPPING
    MARKDOWN_SUPPORT
    TOC_INCLUDE_HEADINGS
    AUTOLINK_SUPPORT
    BUILTIN_STL_SUPPORT
    CPP_CLI_SUPPORT
    SIP_SUPPORT
    IDL_PROPERTY_SUPPORT
    DISTRIBUTE_GROUP_DOC
    GROUP_NESTED_COMPOUNDS
    SUBGROUPING
    INLINE_GROUPED_CLASSES
    INLINE_SIMPLE_STRUCTS
    TYPEDEF_HIDES_STRUCT
    LOOKUP_CACHE_SIZE
    # ---------------------------------------------------------------------------
    # Build related configuration options
    # ---------------------------------------------------------------------------
    EXTRACT_ALL
    EXTRACT_PRIVATE
    EXTRACT_PRIV_VIRTUAL
    EXTRACT_PACKAGE
    EXTRACT_STATIC
    EXTRACT_LOCAL_CLASSES
    EXTRACT_LOCAL_METHODS
    EXTRACT_ANON_NSPACES
    HIDE_UNDOC_MEMBERS
    HIDE_UNDOC_CLASSES
    HIDE_FRIEND_COMPOUNDS
    HIDE_IN_BODY_DOCS
    INTERNAL_DOCS
    CASE_SENSE_NAMES
    HIDE_SCOPE_NAMES
    HIDE_COMPOUND_REFERENCE=
    SHOW_INCLUDE_FILES
    SHOW_GROUPED_MEMB_INC
    FORCE_LOCAL_INCLUDES
    INLINE_INFO
    SORT_MEMBER_DOCS
    SORT_BRIEF_DOCS
    SORT_MEMBERS_CTORS_1ST
    SORT_GROUP_NAMES
    SORT_BY_SCOPE_NAME
    STRICT_PROTO_MATCHING
    GENERATE_TODOLIST
    GENERATE_TESTLIST
    GENERATE_BUGLIST
    GENERATE_DEPRECATEDLIST=
    ENABLED_SECTIONS
    MAX_INITIALIZER_LINES
    SHOW_USED_FILES
    SHOW_FILES
    SHOW_NAMESPACES
    FILE_VERSION_FILTER
    LAYOUT_FILE
    CITE_BIB_FILES
    # ---------------------------------------------------------------------------
    # Configuration options related to warning and progress messages
    # ---------------------------------------------------------------------------
    QUIET
    WARNINGS
    WARN_IF_UNDOCUMENTED
    WARN_IF_DOC_ERROR
    WARN_NO_PARAMDOC
    WARN_AS_ERROR
    WARN_FORMAT
    WARN_LOGFILE
    # ---------------------------------------------------------------------------
    # Configuration options related to the input files
    # ---------------------------------------------------------------------------
    INPUT
    INPUT_ENCODING
    FILE_PATTERNS
    RECURSIVE
    EXCLUDE
    EXCLUDE_SYMLINKS
    EXCLUDE_PATTERNS
    EXCLUDE_SYMBOLS
    EXAMPLE_PATH
    EXAMPLE_PATTERNS
    EXAMPLE_RECURSIVE
    IMAGE_PATH
    INPUT_FILTER
    FILTER_PATTERNS
    FILTER_SOURCE_FILES
    FILTER_SOURCE_PATTERNS
    USE_MDFILE_AS_MAINPAGE
    # ---------------------------------------------------------------------------
    # Configuration options related to source browsing
    # ---------------------------------------------------------------------------
    SOURCE_BROWSER
    INLINE_SOURCES
    STRIP_CODE_COMMENTS
    REFERENCED_BY_RELATION
    REFERENCES_RELATION
    REFERENCES_LINK_SOURCE
    SOURCE_TOOLTIPS
    USE_HTAGS
    VERBATIM_HEADERS
    # ---------------------------------------------------------------------------
    # Configuration options related to the alphabetical class index
    # ---------------------------------------------------------------------------
    ALPHABETICAL_INDEX
    COLS_IN_ALPHA_INDEX
    IGNORE_PREFIX
    # ---------------------------------------------------------------------------
    # Configuration options related to the HTML output
    # ---------------------------------------------------------------------------
    GENERATE_HTML
    HTML_OUTPUT
    HTML_FILE_EXTENSION
    HTML_HEADER
    HTML_FOOTER
    HTML_STYLESHEET
    HTML_EXTRA_STYLESHEET
    HTML_EXTRA_FILES
    HTML_COLORSTYLE_HUE
    HTML_COLORSTYLE_SAT
    HTML_COLORSTYLE_GAMMA
    HTML_TIMESTAMP
    HTML_DYNAMIC_MENUS
    HTML_DYNAMIC_SECTIONS
    HTML_INDEX_NUM_ENTRIES
    GENERATE_DOCSET
    DOCSET_FEEDNAME
    DOCSET_BUNDLE_ID
    DOCSET_PUBLISHER_ID
    DOCSET_PUBLISHER_NAME
    GENERATE_HTMLHELP
    CHM_FILE
    HHC_LOCATION
    GENERATE_CHI
    CHM_INDEX_ENCODING
    BINARY_TOC
    TOC_EXPAND
    GENERATE_QHP
    QCH_FILE
    QHP_NAMESPACE
    QHP_VIRTUAL_FOLDER
    QHP_CUST_FILTER_NAME
    QHP_CUST_FILTER_ATTRS
    QHP_SECT_FILTER_ATTRS
    QHG_LOCATION
    GENERATE_ECLIPSEHELP
    ECLIPSE_DOC_ID
    DISABLE_INDEX
    GENERATE_TREEVIEW
    ENUM_VALUES_PER_LINE
    TREEVIEW_WIDTH
    EXT_LINKS_IN_WINDOW
    HTML_FORMULA_FORMAT
    FORMULA_FONTSIZE
    FORMULA_TRANSPARENT
    FORMULA_MACROFILE
    USE_MATHJAX
    MATHJAX_FORMAT
    MATHJAX_RELPATH
    MATHJAX_EXTENSIONS
    MATHJAX_CODEFILE
    MATHJAX_VERSION
    SEARCHENGINE
    SERVER_BASED_SEARCH
    EXTERNAL_SEARCH
    SEARCHENGINE_URL
    SEARCHDATA_FILE
    EXTERNAL_SEARCH_ID
    EXTRA_SEARCH_MAPPINGS
    # ---------------------------------------------------------------------------
    # Configuration options related to the LaTeX output
    # ---------------------------------------------------------------------------
    GENERATE_LATEX
    LATEX_OUTPUT
    LATEX_CMD_NAME
    MAKEINDEX_CMD_NAME
    LATEX_MAKEINDEX_CMD
    COMPACT_LATEX
    PAPER_TYPE
    EXTRA_PACKAGES
    LATEX_HEADER
    LATEX_FOOTER
    LATEX_EXTRA_STYLESHEET
    LATEX_EXTRA_FILES
    PDF_HYPERLINKS
    USE_PDFLATEX
    LATEX_BATCHMODE
    LATEX_HIDE_INDICES
    LATEX_SOURCE_CODE
    LATEX_BIB_STYLE
    LATEX_TIMESTAMP
    LATEX_EMOJI_DIRECTORY
    # ---------------------------------------------------------------------------
    # Configuration options related to the RTF output
    # ---------------------------------------------------------------------------
    GENERATE_RTF
    RTF_OUTPUT
    COMPACT_RTF
    RTF_HYPERLINKS
    RTF_STYLESHEET_FILE
    RTF_EXTENSIONS_FILE
    RTF_SOURCE_CODE
    # ---------------------------------------------------------------------------
    # Configuration options related to the man page output
    # ---------------------------------------------------------------------------
    GENERATE_MAN
    MAN_OUTPUT
    MAN_EXTENSION
    MAN_SUBDIR
    MAN_LINKS
    # ---------------------------------------------------------------------------
    # Configuration options related to the XML output
    # ---------------------------------------------------------------------------
    GENERATE_XML
    XML_OUTPUT
    XML_PROGRAMLISTING
    XML_NS_MEMB_FILE_SCOPE
    # ---------------------------------------------------------------------------
    # Configuration options related to the DOCBOOK output
    # ---------------------------------------------------------------------------
    GENERATE_DOCBOOK
    DOCBOOK_OUTPUT
    DOCBOOK_PROGRAMLISTING
    # ---------------------------------------------------------------------------
    # Configuration options for the AutoGen Definitions output
    # ---------------------------------------------------------------------------
    GENERATE_AUTOGEN_DEF
    # ---------------------------------------------------------------------------
    # Configuration options related to the Perl module output
    # ---------------------------------------------------------------------------
    GENERATE_PERLMOD
    PERLMOD_LATEX
    PERLMOD_PRETTY
    PERLMOD_MAKEVAR_PREFIX
    # ---------------------------------------------------------------------------
    # Configuration options related to the preprocessor
    # ---------------------------------------------------------------------------
    ENABLE_PREPROCESSING
    MACRO_EXPANSION
    EXPAND_ONLY_PREDEF
    SEARCH_INCLUDES
    INCLUDE_PATH
    INCLUDE_FILE_PATTERNS
    PREDEFINED
    EXPAND_AS_DEFINED
    SKIP_FUNCTION_MACROS
    # ---------------------------------------------------------------------------
    # Configuration options related to external references
    # ---------------------------------------------------------------------------
    TAGFILES
    GENERATE_TAGFILE
    ALLEXTERNALS
    EXTERNAL_GROUPS
    EXTERNAL_PAGES
    # ---------------------------------------------------------------------------
    # Configuration options related to the dot tool
    # ---------------------------------------------------------------------------
    CLASS_DIAGRAMS
    DIA_PATH
    HIDE_UNDOC_RELATIONS
    HAVE_DOT
    DOT_NUM_THREADS
    DOT_FONTNAME
    DOT_FONTSIZE
    DOT_FONTPATH
    CLASS_GRAPH
    COLLABORATION_GRAPH
    GROUP_GRAPHS
    UML_LOOK
    UML_LIMIT_NUM_FIELDS
    TEMPLATE_RELATIONS
    INCLUDE_GRAPH
    INCLUDED_BY_GRAPH
    CALL_GRAPH
    CALLER_GRAPH
    GRAPHICAL_HIERARCHY
    DIRECTORY_GRAPH
    DOT_IMAGE_FORMAT
    INTERACTIVE_SVG
    DOT_PATH
    DOTFILE_DIRS
    MSCFILE_DIRS
    DIAFILE_DIRS
    PLANTUML_JAR_PATH
    PLANTUML_CFG_FILE
    PLANTUML_INCLUDE_PATH
    DOT_GRAPH_MAX_NODES
    MAX_DOT_GRAPH_DEPTH
    DOT_TRANSPARENT
    DOT_MULTI_TARGETS
    GENERATE_LEGEND
    DOT_CLEANUP
  )
    if(DEFINED DOXYGEN_${option})
      file(APPEND ${configfile} "${option} = ${DOXYGEN_${option}}\n")
    endif()
  endforeach()
endmacro(_SETUP_DOXYGEN_CONFIG_FILE)

macro(_set_if_undefined variable)
  if(NOT DEFINED ${variable})
    set(${variable} ${ARGN})
  endif()
endmacro()

# _SETUP_MATHJAX_DEFAULTS
# ----------------------------
#
# Set MathJax defaults depending on the current version of Doxygen and whether
# some flags were already set.
#
# If the Doxygen version is less than 1.9.2, the DOXYGEN_MATHJAX_VERSION option will be unset.
# If a path to MathJax is not provided, we will either:
#   - point to our local vendored version of MathJax 3
#   - unset the MathJax path; the Doxygen HTML header will point to the MathJax 2 CDN.
macro(_SETUP_MATHJAX_DEFAULTS)
  if(DOXYGEN_VERSION VERSION_GREATER_EQUAL 1.9.2)
    _set_if_undefined(DOXYGEN_MATHJAX_VERSION MathJax_3)
  else()
    # remove unsupported option
    unset(DOXYGEN_MATHJAX_VERSION)
    message(
      STATUS
      "Doxygen version inferior to 1.9.2. If MathJax is enabled, v2.7 will be used."
    )
    # set to empty string to use the MathJax CDN
  endif()
  if("${DOXYGEN_MATHJAX_VERSION}" STREQUAL "MathJax_3")
    # If using MathJax 3, use our vendored version by default.
    _set_if_undefined(
      DOXYGEN_MATHJAX_RELPATH
      ${PROJECT_JRL_CMAKE_MODULE_DIR}/doxygen/MathJax
    )
  else()
    _set_if_undefined(DOXYGEN_MATHJAX_RELPATH)
  endif()
endmacro(_SETUP_MATHJAX_DEFAULTS)

# _SETUP_DOXYGEN_DEFAULT_OPTIONS
# ----------------------------
#
# Set default options for doxygen configuration when the user didn't specify
# those options already.
macro(_SETUP_DOXYGEN_DEFAULT_OPTIONS)
  # ---------------------------------------------------------------------------
  # Project related configuration options
  # ---------------------------------------------------------------------------
  _set_if_undefined(DOXYGEN_PROJECT_NAME "${PROJECT_NAME}")
  _set_if_undefined(DOXYGEN_PROJECT_NUMBER "${PROJECT_VERSION}")
  _set_if_undefined(DOXYGEN_PROJECT_BRIEF "\"${PROJECT_DESCRIPTION}\"")
  _set_if_undefined(DOXYGEN_STRIP_FROM_PATH "${PROJECT_SOURCE_DIR}")
  _set_if_undefined(
    DOXYGEN_STRIP_FROM_INC_PATH
    "${PROJECT_SOURCE_DIR}/src ${PROJECT_SOURCE_DIR}/include"
  )
  _set_if_undefined(DOXYGEN_EXTRACT_ALL "YES")
  # ---------------------------------------------------------------------------
  # Configuration options related to warning and progress messages
  # ---------------------------------------------------------------------------
  _set_if_undefined(DOXYGEN_QUIET YES)
  _set_if_undefined(DOXYGEN_WARN_LOGFILE doxygen.log)
  # ---------------------------------------------------------------------------
  # Configuration options related to the input files
  # ---------------------------------------------------------------------------
  _set_if_undefined(DOXYGEN_IMAGE_PATH "${PROJECT_SOURCE_DIR}/doc")
  _set_if_undefined(
    DOXYGEN_FILE_PATTERNS
    "*.cc *.cpp *.h *.hh *.hpp *.hxx *.idl"
  )
  _set_if_undefined(DOXYGEN_RECURSIVE YES)
  # ---------------------------------------------------------------------------
  # Configuration options related to source browsing
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options related to the alphabetical class index
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options related to the HTML output
  # ---------------------------------------------------------------------------
  _set_if_undefined(DOXYGEN_HTML_OUTPUT doxygen-html)
  _set_if_undefined(DOXYGEN_GENERATE_TREEVIEW YES)
  _SETUP_MATHJAX_DEFAULTS()
  # ---------------------------------------------------------------------------
  # Configuration options related to the LaTeX output
  # ---------------------------------------------------------------------------
  _set_if_undefined(DOXYGEN_GENERATE_LATEX NO)
  _set_if_undefined(DOXYGEN_LATEX_OUTPUT doxygen-latex)
  _set_if_undefined(DOXYGEN_EXTRA_PACKAGES "amssymb,amsmath")
  # ---------------------------------------------------------------------------
  # Configuration options related to the RTF output
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options related to the man page output
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options related to the XML output
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options related to the DOCBOOK output
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options for the AutoGen Definitions output
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options related to the Perl module output
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options related to the preprocessor
  # ---------------------------------------------------------------------------

  # ---------------------------------------------------------------------------
  # Configuration options related to external references
  # ---------------------------------------------------------------------------
  _set_if_undefined(
    DOXYGEN_GENERATE_TAGFILE
    "doxygen-html/${PROJECT_NAME}.doxytag"
  )
  # ---------------------------------------------------------------------------
  # Configuration options related to the dot tool
  # ---------------------------------------------------------------------------
endmacro(_SETUP_DOXYGEN_DEFAULT_OPTIONS)

# _SETUP_PROJECT_DOCUMENTATION
# ----------------------------
#
# Look for Doxygen, add a custom rule to generate the documentation and install
# the documentation properly.
#
# Available user options (to be set before calling SETUP_PROJECT):
# DOXYGEN_DOT_IMAGE_FORMAT: format for dot images. Defaults to "svg".
# DOXYGEN_USE_MATHJAX: use MathJax to render LaTeX equations. Defaults to "NO".
macro(_SETUP_PROJECT_DOCUMENTATION)
  # Search for Doxygen.
  find_package(Doxygen)

  if(NOT DOXYGEN_FOUND)
    message(
      STATUS
      "Failed to find Doxygen, documentation will not be generated."
    )
  else(NOT DOXYGEN_FOUND)
    get_directory_property(has_parent_scope PARENT_DIRECTORY)
    set(JRL_CMAKEMODULE_DOXYFILE_PATH "${PROJECT_BINARY_DIR}/doc/Doxyfile")
    if(has_parent_scope)
      set(DOXYGEN_FOUND ${DOXYGEN_FOUND} PARENT_SCOPE)
      set(
        JRL_CMAKEMODULE_DOXYFILE_PATH
        ${JRL_CMAKEMODULE_DOXYFILE_PATH}
        PARENT_SCOPE
      )
    endif(has_parent_scope)
    unset(has_parent_scope)

    _SETUP_DOXYGEN_DEFAULT_OPTIONS()
    # Generate variable to be substitued in Doxyfile.in for dot use.
    if(DOXYGEN_DOT_FOUND)
      set(DOXYGEN_HAVE_DOT YES)
    endif(DOXYGEN_DOT_FOUND)

    # Teach CMake how to generate the documentation.
    if(MSVC)
      # FIXME: it is impossible to trigger documentation installation at
      # install, so put the target in ALL instead.
      if(NOT TARGET doc)
        add_custom_target(doc ALL COMMENT "Generating Doxygen documentation")
      endif()
      add_custom_target(
        ${PROJECT_NAME}-doc
        COMMAND ${DOXYGEN_EXECUTABLE} ${JRL_CMAKEMODULE_DOXYFILE_PATH}
        WORKING_DIRECTORY doc
        COMMENT "Generating Doxygen documentation"
      )
    else(MSVC)
      if(NOT TARGET doc)
        add_custom_target(doc COMMENT "Generating Doxygen documentation")
      endif()

      add_custom_target(
        ${PROJECT_NAME}-doc
        COMMAND ${DOXYGEN_EXECUTABLE} ${JRL_CMAKEMODULE_DOXYFILE_PATH}
        WORKING_DIRECTORY doc
        COMMENT "Generating Doxygen documentation"
      )

      if(INSTALL_DOCUMENTATION)
        install(
          CODE
            "EXECUTE_PROCESS(COMMAND ${CMAKE_MAKE_PROGRAM} ${PROJECT_NAME}-doc)"
        )
      endif(INSTALL_DOCUMENTATION)
    endif(MSVC)
    add_dependencies(doc ${PROJECT_NAME}-doc)

    add_custom_command(
      OUTPUT ${PROJECT_BINARY_DIR}/doc/doxygen-html
      COMMAND ${DOXYGEN_EXECUTABLE} ${JRL_CMAKEMODULE_DOXYFILE_PATH}
      WORKING_DIRECTORY doc
      COMMENT "Generating Doxygen documentation"
    )

    # Clean generated files.
    set_property(
      DIRECTORY
      APPEND
      PROPERTY
        ADDITIONAL_MAKE_CLEAN_FILES
          ${PROJECT_BINARY_DIR}/doc/doxygen.log
          ${PROJECT_BINARY_DIR}/doc/doxygen-html
    )

    if(DEFINED DOXYGEN_HTML_STYLESHEET)
      message(
        WARNING
        "The CMake variable DOXYGEN_HTML_STYLESHEET is defined, which sets the "
        "deprecated Doxygen option HTML_STYLESHEET. It may be broken in the future."
        " Set HTML_STYLESHEET instead."
      )
    endif()

    # Copy our vendored MathJax.
    if("${DOXYGEN_USE_MATHJAX}" STREQUAL "YES")
      file(
        COPY ${PROJECT_JRL_CMAKE_MODULE_DIR}/doxygen/MathJax
        DESTINATION ${PROJECT_BINARY_DIR}/doc/doxygen-html
      )
      # the variable is unset if Doxygen version < 1.9.2
      # otherwise, MathJax_3 is the default.
      if(DOXYGEN_MATHJAX_VERSION STREQUAL "MathJax_3")
        message(
          STATUS
          "MathJax version 3 will be used. If MATHJAX_RELPATH is unset we will use the vendored MathJax. "
          "If you have set it, check that it's pointing at a MathJax 3 distribution."
        )
      endif()
    endif()

    # Install generated files.
    if(INSTALL_DOCUMENTATION)
      install(
        DIRECTORY ${PROJECT_BINARY_DIR}/doc/doxygen-html
        DESTINATION ${CMAKE_INSTALL_FULL_DOCDIR}
      )

      if(EXISTS ${PROJECT_SOURCE_DIR}/doc/pictures)
        install(
          DIRECTORY ${PROJECT_SOURCE_DIR}/doc/pictures
          DESTINATION ${CMAKE_INSTALL_FULL_DOCDIR}/doxygen-html
        )
      endif(EXISTS ${PROJECT_SOURCE_DIR}/doc/pictures)
    endif(INSTALL_DOCUMENTATION)

    list(
      APPEND
      LOGGING_WATCHED_VARIABLES
      DOXYGEN_SKIP_DOT
      DOXYGEN_EXECUTABLE
      DOXYGEN_FOUND
      DOXYGEN_DOT_EXECUTABLE
      DOXYGEN_DOT_FOUND
      DOXYGEN_DOT_PATH
      DOXYGEN_DOT_IMAGE_FORMAT
      DOXYGEN_USE_MATHJAX
      DOXYGEN_USE_TEMPLATE_CSS
    )
  endif(NOT DOXYGEN_FOUND)
endmacro(_SETUP_PROJECT_DOCUMENTATION)

# _DOXYTAG_ENTRIES_FROM_CMAKE_DEPENDENCIES
# ----------------------------------------
#
# Generate TAGFILES entries from this project dependencies and their
# dependencies (recursively)
#
macro(_DOXYTAG_ENTRIES_FROM_CMAKE_DEPENDENCIES DEPENDENCIES VAR_OUT)
  foreach(PREFIX ${DEPENDENCIES})
    if(
      DEFINED ${PREFIX}_DOXYGENDOCDIR
      AND EXISTS ${${PREFIX}_DOXYGENDOCDIR}/${PREFIX}.doxytag
    )
      get_filename_component(DEP_DOCDIR "${${PREFIX}_DOXYGENDOCDIR}" ABSOLUTE)
      list(
        APPEND
        ${VAR_OUT}
        "\"${${PREFIX}_DOXYGENDOCDIR}/${PREFIX}.doxytag = ${DEP_DOCDIR}\""
      )
    endif()
    if(DEFINED ${PREFIX}_DEPENDENCIES)
      _DOXYTAG_ENTRIES_FROM_CMAKE_DEPENDENCIES(
        "${${PREFIX}_DEPENDENCIES}"
        ${VAR_OUT}
      )
    endif()
  endforeach()
endmacro()

# _SETUP_PROJECT_DOCUMENTATION_FINALIZE
# -------------------------------------
#
# Post-processing for the documentation generation macro.
#
# Doxyfile.extra and Doxyfile files are generated at the end to allow the
# replacement of user-defined variables.
#
# Additional doxygen tagfiles from dependencies can be added to
# `DOXYGEN_TAGFILES_FROM_DEPENDENCIES`
#
macro(_SETUP_PROJECT_DOCUMENTATION_FINALIZE)
  if(DOXYGEN_FOUND)
    if(NOT "${DOXYGEN_USE_MATHJAX}" STREQUAL "YES")
      # Make sure latex, dvips and gs are available
      find_program(LATEX latex DOC "LaTeX compiler")
      find_program(DVIPS dvips DOC "DVI to PostScript converter")
      find_program(GS gs DOC "GhostScript interpreter")

      if(NOT (LATEX AND GS AND DVIPS))
        message(
          STATUS
          "Failed to find latex/dvips/gs, will use MathJax backend."
        )
        set(DOXYGEN_USE_MATHJAX "YES")
      endif()
    endif()
    if(INSTALL_DOCUMENTATION)
      # Find doxytag files. To ignore this list of tag files,
      # set the DOXYGEN_TAGFILES CMake variable or TAGFILES in doc/Doxyfile.extra.in.
      set(_TAGFILES_FROM_DEPENDENCIES ${DOXYGEN_TAGFILES_FROM_DEPENDENCIES})
      set(PKG_REQUIRES ${_PKG_CONFIG_REQUIRES})
      list(APPEND PKG_REQUIRES ${_PKG_CONFIG_COMPILE_TIME_REQUIRES})
      foreach(PKG_CONFIG_STRING ${PKG_REQUIRES})
        _PARSE_PKG_CONFIG_STRING(
          ${PKG_CONFIG_STRING}
          LIBRARY_NAME
          PREFIX
          PKG_CONFIG_STRING_NOSPACE
        )
        # If DOXYGENDOCDIR is specified, add a doc path.
        if(
          DEFINED ${PREFIX}_DOXYGENDOCDIR
          AND EXISTS ${${PREFIX}_DOXYGENDOCDIR}/${LIBRARY_NAME}.doxytag
        )
          # always use absolute path
          get_filename_component(
            DEP_DOCDIR
            "${${PREFIX}_DOXYGENDOCDIR}"
            ABSOLUTE
          )
          list(
            APPEND
            _TAGFILES_FROM_DEPENDENCIES
            "\"${${PREFIX}_DOXYGENDOCDIR}/${LIBRARY_NAME}.doxytag = ${DEP_DOCDIR}\""
          )
        endif()
      endforeach()
      _DOXYTAG_ENTRIES_FROM_CMAKE_DEPENDENCIES(
        "${_PACKAGE_CONFIG_DEPENDENCIES_PROJECTS}"
        _TAGFILES_FROM_DEPENDENCIES
      )
      if(_TAGFILES_FROM_DEPENDENCIES)
        # use native deduplication routine for comma-separated lists, then
        # convert comma-separated list to space-separated list string.
        list(REMOVE_DUPLICATES _TAGFILES_FROM_DEPENDENCIES)
        string(
          REPLACE
          ";"
          " "
          DOXYGEN_TAGFILES_FROM_DEPENDENCIES
          "${_TAGFILES_FROM_DEPENDENCIES}"
        )
      endif()
    endif()
    _set_if_undefined(DOXYGEN_TAGFILES "${DOXYGEN_TAGFILES_FROM_DEPENDENCIES}")

    if(EXISTS ${PROJECT_SOURCE_DIR}/include)
      set(
        DOXYGEN_INCLUDE_PATH
        "${DOXYGEN_INCLUDE_PATH} \"${PROJECT_SOURCE_DIR}/include\""
      )
      set(DOXYGEN_INPUT "${DOXYGEN_INPUT} \"${PROJECT_SOURCE_DIR}/include\"")
    endif()
    if(EXISTS ${PROJECT_SOURCE_DIR}/src)
      set(DOXYGEN_INPUT "${DOXYGEN_INPUT} \"${PROJECT_SOURCE_DIR}/src\"")
    endif()
    if(EXISTS ${PROJECT_SOURCE_DIR}/tests)
      set(
        DOXYGEN_EXAMPLE_PATH
        "${DOXYGEN_EXAMPLE_PATH} \"${PROJECT_SOURCE_DIR}/tests\""
      )
    endif()
    set(
      DOXYGEN_INCLUDE_PATH
      "${DOXYGEN_INCLUDE_PATH} \"${PROJECT_BINARY_DIR}/include\""
    )

    # Generate Doxyfile and Doxyfile.extra.
    if(EXISTS ${PROJECT_SOURCE_DIR}/doc/Doxyfile.extra.in)
      configure_file(
        ${PROJECT_SOURCE_DIR}/doc/Doxyfile.extra.in
        ${PROJECT_BINARY_DIR}/doc/Doxyfile.extra
        @ONLY
      )
      # Generate Doxyfile.
      _SETUP_DOXYGEN_CONFIG_FILE(${JRL_CMAKEMODULE_DOXYFILE_PATH})
      file(STRINGS ${PROJECT_BINARY_DIR}/doc/Doxyfile.extra doxyfile_extra)
      foreach(x ${doxyfile_extra})
        file(APPEND ${JRL_CMAKEMODULE_DOXYFILE_PATH} ${x} "\n")
      endforeach(x in doxyfile_extra)
    else()
      # This is kept for bacward compatibility. It was the only thing left in
      # doxygen/Doxyfile.extra.in
      set(DOXYGEN_IMAGE_PATH "${PROJECT_SOURCE_DIR}/doc/pictures")
      # Generate Doxyfile.
      _SETUP_DOXYGEN_CONFIG_FILE(${JRL_CMAKEMODULE_DOXYFILE_PATH})
    endif()
  endif(DOXYGEN_FOUND)
endmacro(_SETUP_PROJECT_DOCUMENTATION_FINALIZE)