From 18a542b92d5381e9392b3110e85bdd3367a4ba19 Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Mon, 16 Dec 2024 18:29:10 +0100 Subject: [PATCH 1/5] add container images for Doxygen --- .devcontainer/doxygen-cgal/Dockerfile | 55 +++++++++++++++++++ .devcontainer/doxygen-cgal/Makefile | 23 ++++++++ .../cgal-NO_ADDITIONAL_DETAILS.patch | 44 +++++++++++++++ .devcontainer/doxygen-cgal/devcontainer.json | 14 +++++ .devcontainer/doxygen-cgal/distrobox.ini | 29 ++++++++++ 5 files changed, 165 insertions(+) create mode 100644 .devcontainer/doxygen-cgal/Dockerfile create mode 100644 .devcontainer/doxygen-cgal/Makefile create mode 100644 .devcontainer/doxygen-cgal/cgal-NO_ADDITIONAL_DETAILS.patch create mode 100644 .devcontainer/doxygen-cgal/devcontainer.json create mode 100644 .devcontainer/doxygen-cgal/distrobox.ini diff --git a/.devcontainer/doxygen-cgal/Dockerfile b/.devcontainer/doxygen-cgal/Dockerfile new file mode 100644 index 000000000000..81cb1f954ce2 --- /dev/null +++ b/.devcontainer/doxygen-cgal/Dockerfile @@ -0,0 +1,55 @@ +# Use an official Fedora as a parent image for the build stage +FROM fedora:latest AS sources_deps + +# Set environment variables to non-interactive +ENV DEBIAN_FRONTEND=noninteractive + +# Install dependencies +RUN dnf update -y && dnf install -y \ + wget \ + make \ + gcc \ + gcc-c++ \ + patch \ + cmake \ + bison \ + flex \ + unzip \ + python3 \ + && dnf clean all + +# Copy the patch file to the build context +COPY cgal-NO_ADDITIONAL_DETAILS.patch . + +FROM sources_deps AS build + +# Build and install Doxygen from sources +ARG DOXYGEN_VERSION=1.9.6 +ARG MAKEFLAGS=-j$(nproc) +RUN if [ -n "$DEBUG"];then set -x && make --version && ls -lZ /tmp && id; fi \ + && DOXYGEN_VERSION_UNDERSCORE=$(echo ${DOXYGEN_VERSION} | sed 's/\./_/g') \ + && wget https://github.com/doxygen/doxygen/archive/refs/tags/Release_${DOXYGEN_VERSION_UNDERSCORE}.zip \ + && unzip Release_${DOXYGEN_VERSION_UNDERSCORE}.zip \ + && cd doxygen-Release_${DOXYGEN_VERSION_UNDERSCORE} \ + && patch -p1 < ../cgal-NO_ADDITIONAL_DETAILS.patch \ + && mkdir build \ + && cd build \ + && cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release .. \ + && cmake --build . \ + && cmake --install . \ + && mkdir -p /usr/local/share/doc/doxygen && cp ../LICENSE /usr/local/share/doc/doxygen/LICENSE.TXT \ + && cd ../.. \ + && rm -rf doxygen-Release_${DOXYGEN_VERSION_UNDERSCORE} Release_${DOXYGEN_VERSION_UNDERSCORE}.zip + +# Use a smaller base image for the final stage +FROM fedora:latest + +# Install necessary runtime dependencies +RUN set -x \ + && dnf update -y && dnf install -y graphviz 'perl(Getopt::Std)' tex-bibtex cmake python3-lxml python3-pyquery \ + && dnf clean all + +# Copy Doxygen from the build stage +COPY --from=build /usr/local/bin/doxygen /usr/local/bin +COPY --from=build /usr/local/share/doc/doxygen/LICENSE.TXT /usr/local/share/doc/doxygen/LICENSE.TXT +RUN doxygen --version diff --git a/.devcontainer/doxygen-cgal/Makefile b/.devcontainer/doxygen-cgal/Makefile new file mode 100644 index 000000000000..9413173b5a73 --- /dev/null +++ b/.devcontainer/doxygen-cgal/Makefile @@ -0,0 +1,23 @@ +SHELL := /bin/bash +DOXYGEN_VERSIONS := 1.12.0 1.11.0 1.10.0 1.9.8 1.9.7 1.9.6 + +.PHONY: all build-% push-% build push + +all: build + @echo "Use `$(MAKE) push` to push the images to the registry." + +build-%: + @echo "MAKEFLAGS: $(MAKEFLAGS)" + @echo "Building Doxygen version $*..." + if [ "$$(getenforce || true)" == "Enforcing" ]; then Z=:z; else Z=; fi; \ + F="$(MAKEFLAGS)"; F=$${F##*fifo:}; F=$${F%% *}; \ + if [ -p "$$F" ]; then echo "The GNU make FIFO file exists:"; ls -l $$F; VOLUME_ARGS="-v $$F:$$F$$Z"; echo -- $$VOLUME_ARGS; fi; \ + podman build --build-arg DOXYGEN_VERSION=$* --build-arg "MAKEFLAGS=$(MAKEFLAGS)" $$VOLUME_ARGS -t cgal/doxygen:$* . + +push-%: build-% + @echo "Pushing cgal/doxygen:$*..." + podman push cgal/doxygen:$* + +build: $(foreach version,$(DOXYGEN_VERSIONS),build-$(version)) + +push: $(foreach version,$(DOXYGEN_VERSIONS),push-$(version)) diff --git a/.devcontainer/doxygen-cgal/cgal-NO_ADDITIONAL_DETAILS.patch b/.devcontainer/doxygen-cgal/cgal-NO_ADDITIONAL_DETAILS.patch new file mode 100644 index 000000000000..bb6e63b274de --- /dev/null +++ b/.devcontainer/doxygen-cgal/cgal-NO_ADDITIONAL_DETAILS.patch @@ -0,0 +1,44 @@ +diff --git a/src/config.xml b/src/config.xml +index 13910958a6..31f1354e44 100644 +--- a/src/config.xml ++++ b/src/config.xml +@@ -893,6 +893,18 @@ Go to the next section or return to the + \note This will also disable the warnings about undocumented members + that are normally produced when \ref cfg_warnings "WARNINGS" is + set to \c YES. ++]]> ++ ++ ++ ++ ++ +diff --git a/src/memberdef.cpp b/src/memberdef.cpp +index 08d9bf24c5..ab04e994c5 100644 +--- a/src/memberdef.cpp ++++ b/src/memberdef.cpp +@@ -2501,6 +2501,7 @@ bool MemberDefImpl::hasDetailedDescription() const + if (!m_hasDetailedDescriptionCached) + { + bool extractAll = Config_getBool(EXTRACT_ALL); ++ bool xAllNoDetailedSec = Config_getBool(NO_ADDITIONAL_DETAILS); + bool alwaysDetailedSec = Config_getBool(ALWAYS_DETAILED_SEC); + bool repeatBrief = Config_getBool(REPEAT_BRIEF); + bool briefMemberDesc = Config_getBool(BRIEF_MEMBER_DESC); +@@ -2512,7 +2513,7 @@ bool MemberDefImpl::hasDetailedDescription() const + // the member has detailed documentation because the user added some comments + bool docFilter = + // extract all is enabled +- extractAll || ++ (extractAll && !xAllNoDetailedSec) || + // has detailed docs + !documentation().isEmpty() || + // has inbody docs diff --git a/.devcontainer/doxygen-cgal/devcontainer.json b/.devcontainer/doxygen-cgal/devcontainer.json new file mode 100644 index 000000000000..0624727085f7 --- /dev/null +++ b/.devcontainer/doxygen-cgal/devcontainer.json @@ -0,0 +1,14 @@ +{ + "name": "CGAL Doxygen Dev Container", + "image": "docker.io/cgal/doxygen:1.12.0", + "features": { + "ghcr.io/devcontainers/features/git:1.3.2": {} + }, + "customizations": { + "vscode": { + "extensions": [ + "ms-vscode.cmake-tools" + ] + } + }, +} \ No newline at end of file diff --git a/.devcontainer/doxygen-cgal/distrobox.ini b/.devcontainer/doxygen-cgal/distrobox.ini new file mode 100644 index 000000000000..55c7c5464816 --- /dev/null +++ b/.devcontainer/doxygen-cgal/distrobox.ini @@ -0,0 +1,29 @@ +[distrobox-doxygen-1.12.0] +image=cgal/doxygen:1.12.0 +exported_bins="/usr/local/bin/doxygen /usr/bin/perl /usr/bin/cmake /usr/bin/python3" +exported_bins_path=$HOME/.local/bin-doxygen-1.12.0 + +[distrobox-doxygen-1.11.0] +image=cgal/doxygen:1.11.0 +exported_bins="/usr/local/bin/doxygen /usr/bin/perl /usr/bin/cmake /usr/bin/python3" +exported_bins_path=$HOME/.local/bin-doxygen-1.11.0 + +[distrobox-doxygen-1.10.0] +image=cgal/doxygen:1.10.0 +exported_bins="/usr/local/bin/doxygen /usr/bin/perl /usr/bin/cmake /usr/bin/python3" +exported_bins_path=$HOME/.local/bin-doxygen-1.10.0 + +[distrobox-doxygen-1.9.8] +image=cgal/doxygen:1.9.8 +exported_bins="/usr/local/bin/doxygen /usr/bin/perl /usr/bin/cmake /usr/bin/python3" +exported_bins_path=$HOME/.local/bin-doxygen-1.9.8 + +[distrobox-doxygen-1.9.7] +image=cgal/doxygen:1.9.7 +exported_bins="/usr/local/bin/doxygen /usr/bin/perl /usr/bin/cmake /usr/bin/python3" +exported_bins_path=$HOME/.local/bin-doxygen-1.9.7 + +[distrobox-doxygen-1.9.6] +image=cgal/doxygen:1.9.6 +exported_bins="/usr/local/bin/doxygen /usr/bin/perl /usr/bin/cmake /usr/bin/python3" +exported_bins_path=$HOME/.local/bin-doxygen-1.9.6 From a269cd37a6b86f9e7a2544662fb82a87aab6d937 Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Mon, 16 Dec 2024 15:17:37 +0100 Subject: [PATCH 2/5] cgal_stylesheet.css must be taken from ../Manual Revert "Merge pull request #8331 from albert-github/feature/bug_cgal_stylesheet" This reverts commit 62de71bcfb38419fbe9cf1279eb53a91b732e220, reversing changes made to 3b4349cfbb8da2370f11ca67d3436b6714b2c86e. --- Documentation/doc/Documentation/Doxyfile.in | 1 + .../doc/resources/1.10.0/BaseDoxyfile.in | 18 ------------------ Documentation/doc/resources/1.10.0/header.html | 1 + .../doc/resources/1.10.0/header_package.html | 1 + .../doc/resources/1.8.13/BaseDoxyfile.in | 18 ------------------ Documentation/doc/resources/1.8.13/header.html | 1 - .../doc/resources/1.8.13/header_package.html | 1 - .../doc/resources/1.9.6/BaseDoxyfile.in | 18 ------------------ Documentation/doc/resources/1.9.6/header.html | 1 - .../doc/resources/1.9.6/header_package.html | 1 - 10 files changed, 3 insertions(+), 58 deletions(-) diff --git a/Documentation/doc/Documentation/Doxyfile.in b/Documentation/doc/Documentation/Doxyfile.in index 1b174bb8635f..d3e21f24daab 100644 --- a/Documentation/doc/Documentation/Doxyfile.in +++ b/Documentation/doc/Documentation/Doxyfile.in @@ -19,6 +19,7 @@ FILTER_PATTERNS = *.txt=${CMAKE_BINARY_DIR}/pkglist_filter HTML_EXTRA_FILES += ${CGAL_DOC_RESOURCE_DIR}/hacks.js \ ${CGAL_DOC_RESOURCE_DIR}/menu_version.js \ + ${CGAL_DOC_RESOURCE_DIR}/cgal_stylesheet.css \ ${CMAKE_BINARY_DIR}/how_to_cite_cgal.bib \ ${CMAKE_BINARY_DIR}/how_to_cite.html \ ${CGAL_PACKAGE_DOC_DIR}/fig/g-196x196-doc.png diff --git a/Documentation/doc/resources/1.10.0/BaseDoxyfile.in b/Documentation/doc/resources/1.10.0/BaseDoxyfile.in index d37679fa4a5c..0cc706e0f5d2 100644 --- a/Documentation/doc/resources/1.10.0/BaseDoxyfile.in +++ b/Documentation/doc/resources/1.10.0/BaseDoxyfile.in @@ -486,24 +486,6 @@ HTML_HEADER = ${CGAL_DOC_HEADER_PACKAGE} HTML_FOOTER = ${CGAL_DOC_RESOURCE_DIR}/footer.html -# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined -# cascading style sheets that are included after the standard style sheets -# created by doxygen. Using this option one can overrule certain style aspects. -# This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefore more robust against future updates. -# Doxygen will copy the style sheet files to the output directory. -# Note: The order of the extra style sheet files is of importance (e.g. the last -# style sheet in the list overrules the setting of the previous ones in the -# list). -# Note: Since the styling of scrollbars can currently not be overruled in -# Webkit/Chromium, the styling will be left out of the default doxygen.css if -# one or more extra stylesheets have been specified. So if scrollbar -# customization is desired it has to be added explicitly. For an example see the -# documentation. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_EXTRA_STYLESHEET = ${CGAL_DOC_RESOURCE_DIR}/cgal_stylesheet.css - # 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 diff --git a/Documentation/doc/resources/1.10.0/header.html b/Documentation/doc/resources/1.10.0/header.html index 3549905fa84a..0b1efb0d3c48 100644 --- a/Documentation/doc/resources/1.10.0/header.html +++ b/Documentation/doc/resources/1.10.0/header.html @@ -26,6 +26,7 @@ $mathjax $darkmode + $extrastylesheet diff --git a/Documentation/doc/resources/1.10.0/header_package.html b/Documentation/doc/resources/1.10.0/header_package.html index 19b6e358b4ca..d39b6ab93dc0 100644 --- a/Documentation/doc/resources/1.10.0/header_package.html +++ b/Documentation/doc/resources/1.10.0/header_package.html @@ -43,6 +43,7 @@ + $mathjax $darkmode diff --git a/Documentation/doc/resources/1.8.13/BaseDoxyfile.in b/Documentation/doc/resources/1.8.13/BaseDoxyfile.in index 7fb06630c203..4bd2e290d30b 100644 --- a/Documentation/doc/resources/1.8.13/BaseDoxyfile.in +++ b/Documentation/doc/resources/1.8.13/BaseDoxyfile.in @@ -477,24 +477,6 @@ HTML_HEADER = ${CGAL_DOC_HEADER_PACKAGE} HTML_FOOTER = ${CGAL_DOC_RESOURCE_DIR}/footer.html -# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined -# cascading style sheets that are included after the standard style sheets -# created by doxygen. Using this option one can overrule certain style aspects. -# This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefore more robust against future updates. -# Doxygen will copy the style sheet files to the output directory. -# Note: The order of the extra style sheet files is of importance (e.g. the last -# style sheet in the list overrules the setting of the previous ones in the -# list). -# Note: Since the styling of scrollbars can currently not be overruled in -# Webkit/Chromium, the styling will be left out of the default doxygen.css if -# one or more extra stylesheets have been specified. So if scrollbar -# customization is desired it has to be added explicitly. For an example see the -# documentation. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_EXTRA_STYLESHEET = ${CGAL_DOC_RESOURCE_DIR}/cgal_stylesheet.css - # 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 # to YES can help to show when doxygen was last run and thus if the diff --git a/Documentation/doc/resources/1.8.13/header.html b/Documentation/doc/resources/1.8.13/header.html index 8c8b86f5b9dd..3400f24ed80d 100644 --- a/Documentation/doc/resources/1.8.13/header.html +++ b/Documentation/doc/resources/1.8.13/header.html @@ -17,7 +17,6 @@ $search $mathjax - $extrastylesheet diff --git a/Documentation/doc/resources/1.8.13/header_package.html b/Documentation/doc/resources/1.8.13/header_package.html index 544fd3ced7fb..4c3cd1e85916 100644 --- a/Documentation/doc/resources/1.8.13/header_package.html +++ b/Documentation/doc/resources/1.8.13/header_package.html @@ -33,7 +33,6 @@ - - $mathjax $darkmode From 5eddbc26aea445444e480f1c2ad40379d60532df Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Mon, 16 Dec 2024 18:17:11 +0100 Subject: [PATCH 3/5] 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) From 08a3f5240d0647eafe56fe5bac8b9b4a6df0924d Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Tue, 17 Dec 2024 16:02:22 +0100 Subject: [PATCH 4/5] add a few vscode extensions to the dev container --- .devcontainer/doxygen-cgal/devcontainer.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.devcontainer/doxygen-cgal/devcontainer.json b/.devcontainer/doxygen-cgal/devcontainer.json index 0624727085f7..f1c9f05badb7 100644 --- a/.devcontainer/doxygen-cgal/devcontainer.json +++ b/.devcontainer/doxygen-cgal/devcontainer.json @@ -1,5 +1,5 @@ { - "name": "CGAL Doxygen Dev Container", + "name": "CGAL Doxygen Dev Container, version 1.12.0, with CGAL patch", "image": "docker.io/cgal/doxygen:1.12.0", "features": { "ghcr.io/devcontainers/features/git:1.3.2": {} @@ -7,7 +7,9 @@ "customizations": { "vscode": { "extensions": [ - "ms-vscode.cmake-tools" + "ms-vscode.cmake-tools", + "bbenoist.Doxygen", + "ms-vscode.cpptools" ] } }, From 1e06a8813f783780d8c29d73ccd8e06108e44ff6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Loriot?= Date: Wed, 8 Jan 2025 17:31:21 +0100 Subject: [PATCH 5/5] handle special case when FFG has a non-manifold mesh and not all umbrellas are selected --- .../CGAL/boost/graph/copy_face_graph.h | 30 +++++- BGL/test/BGL/test_Face_filtered_graph.cpp | 99 +++++++++++++++++++ 2 files changed, 125 insertions(+), 4 deletions(-) diff --git a/BGL/include/CGAL/boost/graph/copy_face_graph.h b/BGL/include/CGAL/boost/graph/copy_face_graph.h index e0d4cbd5b958..bbd7a12708b9 100644 --- a/BGL/include/CGAL/boost/graph/copy_face_graph.h +++ b/BGL/include/CGAL/boost/graph/copy_face_graph.h @@ -178,6 +178,7 @@ void copy_face_graph_impl(const SourceMesh& sm, TargetMesh& tm, } // detect if there are some non-manifold umbrellas and fix missing halfedge target pointers + std::map> nm_umbrella_map; typedef typename std::vector::iterator edge_iterator; for (edge_iterator it=new_edges.begin(); it!=new_edges.end(); ++it) { @@ -199,10 +200,19 @@ void copy_face_graph_impl(const SourceMesh& sm, TargetMesh& tm, // we recover tm_v using the halfedge associated to the target vertex of // the halfedge in sm corresponding to nh_t. This is working because we // set the vertex halfedge pointer to the "same" halfedges. - tm_vertex_descriptor tm_v = - target( get(hs_to_ht, halfedge(target(get(ht_to_hs, nh_t), sm), sm)), tm); - for(tm_halfedge_descriptor ht : halfedges_around_target(nh_t, tm)) - set_target(ht, tm_v, tm); + + sm_vertex_descriptor vs = target(get(ht_to_hs, nh_t), sm); + sm_halfedge_descriptor hs = halfedge(vs, sm); + if (hs == boost::graph_traits::null_halfedge()) + { // special case for Face_filtered_graph with a non-manifold input with not all umbrellas selected + nm_umbrella_map[vs].push_back(nh_t); + } + else + { + tm_vertex_descriptor tm_v = target( get(hs_to_ht, hs), tm); + for(tm_halfedge_descriptor ht : halfedges_around_target(nh_t, tm)) + set_target(ht, tm_v, tm); + } } nh_t = opposite(nh_t, tm); } @@ -210,6 +220,18 @@ void copy_face_graph_impl(const SourceMesh& sm, TargetMesh& tm, break; } } + + for (const auto& vs_and_hts : nm_umbrella_map) + { + sm_vertex_descriptor v_sm = vs_and_hts.first; + tm_vertex_descriptor v_tm = add_vertex(tm); + *v2v++=std::make_pair(v_sm, v_tm); + set_halfedge(v_tm, vs_and_hts.second.front(), tm); + put(tm_vpm, v_tm, conv(get(sm_vpm, v_sm))); + + for (tm_halfedge_descriptor h_tm : vs_and_hts.second) + set_target(h_tm, v_tm, tm); + } } } // end of namespace internal diff --git a/BGL/test/BGL/test_Face_filtered_graph.cpp b/BGL/test/BGL/test_Face_filtered_graph.cpp index d85c55353a4f..1e02729a4baa 100644 --- a/BGL/test/BGL/test_Face_filtered_graph.cpp +++ b/BGL/test/BGL/test_Face_filtered_graph.cpp @@ -498,6 +498,103 @@ void test_invalid_selections() assert(!many_umbrellas_fg.is_selection_valid()); } + +void non_manifoldness_test1() +{ + // works out-of-the-box because Face_filtered_graph handles already non-manifold cycles + SM mesh; + SM::Vertex_index v0=add_vertex(mesh); + SM::Vertex_index v1=add_vertex(mesh); + SM::Vertex_index v2=add_vertex(mesh); + SM::Vertex_index v3=add_vertex(mesh); + SM::Vertex_index v4=add_vertex(mesh); + SM::Vertex_index v5=add_vertex(mesh); + SM::Vertex_index v6=add_vertex(mesh); + + SM::Face_index f0=mesh.add_face(v0,v1,v2); + SM::Face_index f1=mesh.add_face(v0,v3,v4); + SM::Face_index f2=mesh.add_face(v0,v5,v6); + SM::Halfedge_index h = halfedge(f0,mesh); + while(target(h, mesh)!=v0) + h=next(h,mesh); + set_halfedge(v0, h, mesh); + + std::vector selection = {f1, f2}; + CGAL::Face_filtered_graph ffg(mesh, selection); + + SM out; + CGAL::copy_face_graph(ffg, out); + + assert(vertices(out).size()==5); + assert(faces(out).size()==2); +} + +void non_manifoldness_test2() +{ + SM mesh; + SM::Vertex_index v0=add_vertex(mesh); + SM::Vertex_index v0b=add_vertex(mesh); + SM::Vertex_index v0t=add_vertex(mesh); + + SM::Vertex_index v1=add_vertex(mesh); + SM::Vertex_index v2=add_vertex(mesh); + SM::Vertex_index v3=add_vertex(mesh); + + SM::Vertex_index v4=add_vertex(mesh); + SM::Vertex_index v5=add_vertex(mesh); + SM::Vertex_index v6=add_vertex(mesh); + + SM::Vertex_index v7=add_vertex(mesh); + SM::Vertex_index v8=add_vertex(mesh); + SM::Vertex_index v9=add_vertex(mesh); + + SM::Face_index f00=mesh.add_face(v1,v2,v0); + SM::Face_index f01=mesh.add_face(v2,v3,v0); + SM::Face_index f02=mesh.add_face(v3,v1,v0); + + SM::Face_index f10=mesh.add_face(v4,v5,v0b); + SM::Face_index f11=mesh.add_face(v5,v6,v0b); + SM::Face_index f12=mesh.add_face(v6,v4,v0b); + + SM::Face_index f20=mesh.add_face(v7,v8,v0t); + SM::Face_index f21=mesh.add_face(v8,v9,v0t); + SM::Face_index f22=mesh.add_face(v9,v7,v0t); + + assert(f00!=SM::Face_index()); + assert(f01!=SM::Face_index()); + assert(f02!=SM::Face_index()); + assert(f10!=SM::Face_index()); + assert(f11!=SM::Face_index()); + assert(f12!=SM::Face_index()); + assert(f20!=SM::Face_index()); + assert(f21!=SM::Face_index()); + assert(f22!=SM::Face_index()); + + #define UPDATE_V(fX, vX) \ + { SM::Halfedge_index h = halfedge(fX,mesh);\ + while(target(h, mesh)!=vX) h=next(h,mesh);\ + set_target(h, v0, mesh); } + + UPDATE_V(f10, v0b) + UPDATE_V(f11, v0b) + UPDATE_V(f12, v0b) + UPDATE_V(f20, v0t) + UPDATE_V(f21, v0t) + UPDATE_V(f22, v0t) + + remove_vertex(v0b, mesh); + remove_vertex(v0t, mesh); + + std::vector selection = {f10, f11, f12, f20, f21, f22}; + CGAL::Face_filtered_graph ffg(mesh, selection); + + SM out; + CGAL::copy_face_graph(ffg, out); + + assert(vertices(out).size()==7); + assert(faces(out).size()==6); +} + int main() { test_graph_range(poly_data()); @@ -511,6 +608,8 @@ int main() #endif test_invalid_selections(); + non_manifoldness_test1(); + non_manifoldness_test2(); // Make a tetrahedron and test the adapter for a patch that only contains 2 faces typedef CGAL::Face_filtered_graph SM_Adapter;