From 345b8a4694f3af481d81076bb2df389a87fca9da Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Mon, 16 Dec 2024 18:17:11 +0100 Subject: [PATCH] fix build with Doxygen 1.10 and later --- Documentation/doc/CMakeLists.txt | 48 ++++++++++++++++--- .../Developer_manual/cmakelist_script.txt | 2 +- .../Developer_manual/developer_manual.txt | 1 + .../Doxygen_for_CGAL.md} | 20 ++++---- Documentation/doc/scripts/pkglist_filter.py | 12 ++--- 5 files changed, 57 insertions(+), 26 deletions(-) rename Documentation/doc/{Customizations.txt => Documentation/Doxygen_for_CGAL.md} (77%) diff --git a/Documentation/doc/CMakeLists.txt b/Documentation/doc/CMakeLists.txt index 52ee7faa48be..b251731cafc4 100644 --- a/Documentation/doc/CMakeLists.txt +++ b/Documentation/doc/CMakeLists.txt @@ -24,6 +24,8 @@ else() set(CGAL_ROOT "${CMAKE_SOURCE_DIR}") endif() +cmake_minimum_required(VERSION 3.18..3.29) # for list(SORT ... COMPARE NATURAL) + find_package(Doxygen REQUIRED) find_package(Python3 REQUIRED COMPONENTS Interpreter) @@ -32,7 +34,7 @@ if (NOT Python3_EXECUTABLE) return() endif() -message(STATUS ${Python3_EXECUTABLE}) +message(VERBOSE "Using Python version ${Python3_VERSION}: ${Python3_EXECUTABLE}") if(NOT DOXYGEN_FOUND) message(WARNING "Cannot build the documentation without Doxygen!") @@ -275,7 +277,7 @@ set(CGAL_DOC_DXY_DIR "${CMAKE_BINARY_DIR}/doc_dxy") file(MAKE_DIRECTORY "${CGAL_DOC_DXY_DIR}") #Setting the resource directory depending on the version of doxygen -set(CGAL_DOC_RESOURCE_DIR_DEFAULT "${CMAKE_CURRENT_LIST_DIR}/resources/1.10.0") +set(CGAL_DOC_RESOURCE_PREFIX_DIR "${CMAKE_CURRENT_LIST_DIR}/resources") # first look if resources for the specific doxygen version is available, fallback # on the default otherwise @@ -283,12 +285,46 @@ set(CGAL_DOC_RESOURCE_DIR_DEFAULT "${CMAKE_CURRENT_LIST_DIR}/resources/1.10.0") #select only the version number (not the commit hash) string(REPLACE " " ";" DOXYGEN_VERSION ${DOXYGEN_VERSION}) list(GET DOXYGEN_VERSION 0 DOXYGEN_VERSION) +message(VERBOSE "Doxygen version ${DOXYGEN_VERSION}: ${DOXYGEN_EXECUTABLE}") + +# The Doxygen version is search in that sorted list (to find the index for which the version is less or equal) +set(CGAL_DOXYGEN_RESOURCES_VERSIONS 1.8.13 1.9.6 1.10.0) +list(SORT CGAL_DOXYGEN_RESOURCES_VERSIONS COMPARE NATURAL) + +# The GLOB is here to check that the list in CGAL_DOXYGEN_RESOURCES_VERSIONS is correct. +# CGAL_DOXYGEN_RESOURCES_DIRS is also used below. +file(GLOB CGAL_DOXYGEN_RESOURCES_DIRS + RELATIVE "${CGAL_DOC_RESOURCE_PREFIX_DIR}" + "${CGAL_DOC_RESOURCE_PREFIX_DIR}/*") +list(SORT CGAL_DOXYGEN_RESOURCES_DIRS COMPARE NATURAL) + +if(NOT CGAL_DOXYGEN_RESOURCES_DIRS STREQUAL CGAL_DOXYGEN_RESOURCES_VERSIONS) + message(FATAL "The directories in ${CGAL_DOC_RESOURCE_PREFIX_DIR} do not match the +expected versions: [${CGAL_DOXYGEN_RESOURCES_VERSIONS}] vs [${CGAL_DOXYGEN_RESOURCES_DIRS}]") +endif() -if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/resources/${DOXYGEN_VERSION}") - set(CGAL_DOC_RESOURCE_DIR - "${CMAKE_CURRENT_LIST_DIR}/resources/${DOXYGEN_VERSION}") +function(CGAL_insert_in_sorted_list list_name value) + set(list ${${list_name}}) + if(NOT value IN_LIST list) + list(APPEND list "${value}") + list(SORT list COMPARE NATURAL) + endif() + set(${list_name} ${list} PARENT_SCOPE) +endfunction() + +if(DOXYGEN_VERSION IN_LIST CGAL_DOXYGEN_RESOURCES_VERSIONS) + list(FIND CGAL_DOXYGEN_RESOURCES_VERSIONS "${DOXYGEN_VERSION}" DOXYGEN_VERSION_INDEX) +else() + CGAL_insert_in_sorted_list(CGAL_DOXYGEN_RESOURCES_VERSIONS ${DOXYGEN_VERSION}) + list(FIND CGAL_DOXYGEN_RESOURCES_VERSIONS ${DOXYGEN_VERSION} DOXYGEN_VERSION_INDEX) + math(EXPR DOXYGEN_VERSION_INDEX "${DOXYGEN_VERSION_INDEX} - 1") +endif() +list(GET CGAL_DOXYGEN_RESOURCES_DIRS "${DOXYGEN_VERSION_INDEX}" CGAL_DOC_RESOURCE_DIR) +set(CGAL_DOC_RESOURCE_DIR "${CGAL_DOC_RESOURCE_PREFIX_DIR}/${CGAL_DOC_RESOURCE_DIR}") +if(NOT EXISTS "${CGAL_DOC_RESOURCE_DIR}") + message(FATAL_ERROR "Doxygen resources for version ${DOXYGEN_VERSION} not found") else() - set(CGAL_DOC_RESOURCE_DIR "${CGAL_DOC_RESOURCE_DIR_DEFAULT}") + message(VERBOSE "Using Doxygen resources from ${CGAL_DOC_RESOURCE_DIR}") endif() set(CGAL_DOC_BIBLIO_DIR "${CMAKE_CURRENT_LIST_DIR}/biblio") diff --git a/Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt b/Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt index eeae486b2362..da9bc70ce2a9 100644 --- a/Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt +++ b/Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt @@ -35,6 +35,6 @@ These options should suffice to create a `CMakeLists.txt` script for most directories containing programs. However, in some special cases, it might still be required to create the script manually, for instance, if some source files/executables need a different linking than -other source files. The Section \subpage devman_create_and_use_a_cmakelist provides more details. +other source files. The Section \ref devman_create_and_use_a_cmakelist provides more details. */ diff --git a/Documentation/doc/Documentation/Developer_manual/developer_manual.txt b/Documentation/doc/Documentation/Developer_manual/developer_manual.txt index a133c654abaf..6c3b3f0504aa 100644 --- a/Documentation/doc/Documentation/Developer_manual/developer_manual.txt +++ b/Documentation/doc/Documentation/Developer_manual/developer_manual.txt @@ -23,4 +23,5 @@ The developer manual is primarily aimed at \cgal developers, but may also be int - \subpage devman_info - \subpage devman_create_cgal_CMakeLists - \subpage deprecated +- \subpage Doxygen_for_CGAL */ diff --git a/Documentation/doc/Customizations.txt b/Documentation/doc/Documentation/Doxygen_for_CGAL.md similarity index 77% rename from Documentation/doc/Customizations.txt rename to Documentation/doc/Documentation/Doxygen_for_CGAL.md index c1debd91db60..2c13a7cc0542 100644 --- a/Documentation/doc/Customizations.txt +++ b/Documentation/doc/Documentation/Doxygen_for_CGAL.md @@ -1,4 +1,4 @@ -# Doxygen for CGAL # +\page Doxygen_for_CGAL Doxygen for CGAL This is the documentation of doxygen hacks that are applied to make the output of Doxygen more suitable to CGAL. It explains the general @@ -14,17 +14,17 @@ hacks that create what you see. ### Package Overview ### The package overview is build by having a special command that is -filtered by the python script pkglist_filter.py. +filtered by the python script `pkglist_filter.py`. -A command has to be of the form \package_listing{PKG_NAME}, where -PKG_NAME cannot contain a closing }. +A command has to be of the form `\package_listing{PKG_NAME}`, where +`PKG_NAME` cannot contain a closing `}`. The command is replaced by the text between the two delimiters -PkgDescBegin and PkgDescEnd in the file ../PKG_NAME/doc/PKG_NAME/PackageDescription.txt +`cgalPkgDescriptionBegin` and `cgalPkgDescriptionEnd` in the file `../PKG_NAME/doc/PKG_NAME/PackageDescription.txt` -If PKG_NAME is of the form A/B the selected file is -../A/doc/B/PackageDescription.txt. This is to support packages like -TDS_2, which don't reside in their own packages in the SCM. +If `PKG_NAME` is of the form `A/B` the selected file is +`../A/doc/B/PackageDescription.txt`. This is to support packages like +`TDS_2`, which don't reside in their own packages in the SCM. ### Footnotes ### @@ -50,13 +50,13 @@ LaTex. This hack fiddles with the internal structures and functions of the treeview to remove the unnecessary intermediate top-level module part. -It assigns the first element of the module array (found in module.js) +It assigns the first element of the module array (found in `module.js`) to the Reference Manual entry. This makes the tree view link go to that group directly instead of the intermediate link. It also removes one level of nesting. Unfortunately this changes the overall tree structure. To adjust for -that we hijack the gotoNode function of navtree.js and *augment* it +that we hijack the `gotoNode` function of `navtree.js` and *augment* it with an additional check for the specific tree level we borked and redirect it. diff --git a/Documentation/doc/scripts/pkglist_filter.py b/Documentation/doc/scripts/pkglist_filter.py index 92208a6f4d9c..f6cbff6c7d94 100755 --- a/Documentation/doc/scripts/pkglist_filter.py +++ b/Documentation/doc/scripts/pkglist_filter.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 import codecs import re @@ -28,16 +28,10 @@ def main(argv): for l in pkgdesc: do_print = do_print or re.match(".*cgalPkgDescriptionBegin.*", l) if(do_print): - if hasattr(sys.stdout, 'buffer'): - sys.stdout.buffer.write(l.encode('utf-8')) #python3 - else: - sys.stdout.write(l.encode('utf-8')) #python2 + sys.stdout.buffer.write(l.encode('utf-8')) do_print = do_print and (not re.match(".*cgalPkgDescriptionEnd.*", l)) else: - if hasattr(sys.stdout, 'buffer'): - sys.stdout.buffer.write(line.encode('utf-8')) #python3 - else: - sys.stdout.write(line.encode('utf-8')) #python2 + sys.stdout.buffer.write(line.encode('utf-8')) if __name__ == "__main__": main(sys.argv)