From f81db935cabe1a981b061fe15c7322486dcd55cd Mon Sep 17 00:00:00 2001 From: Kyle Guinn Date: Mon, 15 Jan 2024 15:54:41 -0600 Subject: [PATCH 1/6] Sort Doxygen lists for comparison purposes --- CMakeLists.txt | 2 +- DOCS/Doxyfile | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 5c3818db5d..239d8ce2f4 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -656,13 +656,13 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) html # Doxygen INPUT = - ${PROJECT_SOURCE_DIR}/README.md ${PROJECT_SOURCE_DIR}/BLAS ${PROJECT_SOURCE_DIR}/CBLAS ${PROJECT_SOURCE_DIR}/SRC ${PROJECT_SOURCE_DIR}/INSTALL ${PROJECT_SOURCE_DIR}/TESTING ${PROJECT_SOURCE_DIR}/DOCS/groups-usr.dox + ${PROJECT_SOURCE_DIR}/README.md COMMENT "Generating html LAPACK documentation (it will take some time... time to grab a coffee)" ) diff --git a/DOCS/Doxyfile b/DOCS/Doxyfile index 577675772c..40e47d7f85 100644 --- a/DOCS/Doxyfile +++ b/DOCS/Doxyfile @@ -885,9 +885,9 @@ INPUT_ENCODING = UTF-8 # *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, *.vhdl, # *.ucf, *.qsf and *.ice. -FILE_PATTERNS = *.c \ - *.f \ +FILE_PATTERNS = *.f \ *.f90 \ + *.c \ *.h # The RECURSIVE tag can be used to specify whether or not subdirectories should From 62c9cd885a15208939ff5e62016c8c21a6882226 Mon Sep 17 00:00:00 2001 From: Kyle Guinn Date: Mon, 15 Jan 2024 15:55:41 -0600 Subject: [PATCH 2/6] Skip setting Doxygen options to default values QUIET defaults to NO, WARNINGS defaults to YES. --- CMakeLists.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 239d8ce2f4..6d1651af43 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -627,8 +627,6 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) set(DOXYGEN_GENERATE_TREEVIEW YES) set(DOXYGEN_DOT_IMAGE_FORMAT svg) set(DOXYGEN_INTERACTIVE_SVG YES) - set(DOXYGEN_QUIET NO) - set(DOXYGEN_WARNINGS YES) set(DOXYGEN_WARN_NO_PARAMDOC YES) set(DOXYGEN_WARN_LOGFILE doxygen_error) set(DOXYGEN_GENERATE_HTML NO) From bd6fece37bad29ecc9757ca8e63218328e01d202 Mon Sep 17 00:00:00 2001 From: Kyle Guinn Date: Mon, 15 Jan 2024 16:21:49 -0600 Subject: [PATCH 3/6] Reset several Doxygen options to their default values The goal is to minimize the output of `doxygen -x DOCS/Doxyfile` so that it contains only the settings specified in CMakeLists.txt. In all cases, the changed values are intended to match what CMake is generating when using -DBUILD_HTML_DOCUMENTATION=ON, and ideally the changes should have no effect. Comments for ABBREVIATE_BRIEF and EXAMPLE_PATTERNS describe the default behavior when they are blank, but our blank values show up in the output of `doxygen -x DOCS/Doxyfile` indicating that blank is not the default value. Setting values to match the current default behavior should have no effect, unless Doxygen changes in the future. On the other hand, MATHJAX_RELPATH has changed and will change again in newer Doxygen versions. CMake automatically inserts its own set of EXCLUDE_PATTERNS that contains none of the patterns previously listed here. Neither the previous values nor the CMake-generated ones should have any effect due to our choice of INPUT and FILE_PATTERNS. MATHJAX_RELPATH, LATEX_CMD_NAME, RTF_HYPERLINKS, and MAN_LINKS all require some other option (USE_MATHJAX, GENERATE_LATEX, GENERATE_RTF, and GENERATE_MAN, respectively) to be set to YES to take effect, and all are set to NO, so these changes should have no effect. Note that the CMake-generated Doxyfile.man sets MAN_LINKS=YES in addition to GENERATE_MAN=YES. --- DOCS/Doxyfile | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/DOCS/Doxyfile b/DOCS/Doxyfile index 40e47d7f85..5cdf3208c4 100644 --- a/DOCS/Doxyfile +++ b/DOCS/Doxyfile @@ -126,7 +126,17 @@ REPEAT_BRIEF = YES # the entity):The $name class, The $name widget, The $name file, is, provides, # specifies, contains, represents, a, an and the. -ABBREVIATE_BRIEF = +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # doxygen will generate a detailed section even if there is only a brief @@ -927,11 +937,7 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = *.py \ - *.txt \ - *.in \ - *.inc \ - Makefile +EXCLUDE_PATTERNS = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -955,7 +961,7 @@ EXAMPLE_PATH = # *.h) to filter out the source-files in the directories. If left blank all # files are included. -EXAMPLE_PATTERNS = +EXAMPLE_PATTERNS = * # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands @@ -1602,7 +1608,7 @@ MATHJAX_FORMAT = HTML-CSS # The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. # This tag requires that the tag USE_MATHJAX is set to YES. -MATHJAX_RELPATH = http://www.mathjax.org/mathjax +MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@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 @@ -1735,7 +1741,7 @@ LATEX_OUTPUT = latex # the output language. # This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_CMD_NAME = latex +LATEX_CMD_NAME = # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate # index for LaTeX. @@ -1938,7 +1944,7 @@ COMPACT_RTF = NO # The default value is: NO. # This tag requires that the tag GENERATE_RTF is set to YES. -RTF_HYPERLINKS = YES +RTF_HYPERLINKS = NO # Load stylesheet definitions from file. Syntax is similar to doxygen's # configuration file, i.e. a series of assignments. You only have to provide @@ -2009,7 +2015,7 @@ MAN_SUBDIR = # The default value is: NO. # This tag requires that the tag GENERATE_MAN is set to YES. -MAN_LINKS = YES +MAN_LINKS = NO #--------------------------------------------------------------------------- # Configuration options related to the XML output From cf9b217c50e342639463afc09c7eb23dd38fb8b4 Mon Sep 17 00:00:00 2001 From: Kyle Guinn Date: Mon, 15 Jan 2024 21:55:08 -0600 Subject: [PATCH 4/6] Add options missing from the existing Doxyfile Both have been present in DOCS/Doxyfile since that file was added. --- CMakeLists.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index 6d1651af43..62ff0a7559 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -621,6 +621,7 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) set(DOXYGEN_SOURCE_BROWSER YES) set(DOXYGEN_CREATE_SUBDIRS YES) set(DOXYGEN_SEPARATE_MEMBER_PAGES YES) + set(DOXYGEN_TAB_SIZE 8) set(DOXYGEN_EXTRACT_ALL YES) set(DOXYGEN_FILE_PATTERNS *.f *.f90 *.c *.h ) set(DOXYGEN_RECURSIVE YES) @@ -646,6 +647,7 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) if (BUILD_HTML_DOCUMENTATION) set(DOXYGEN_GENERATE_HTML YES) set(DOXYGEN_HTML_OUTPUT explore-html) + set(DOXYGEN_HTML_TIMESTAMP YES) set(DOXYGEN_INLINE_SOURCES YES) set(DOXYGEN_CALL_GRAPH YES) set(DOXYGEN_CALLER_GRAPH YES) From 7952995ba08b96c339408bee5d3bbbcafce37a39 Mon Sep 17 00:00:00 2001 From: Kyle Guinn Date: Mon, 15 Jan 2024 22:35:16 -0600 Subject: [PATCH 5/6] Adjust Doxygen source and output paths This removes another difference with DOCS/Doxyfile. From the CMake 3.9.6 documentation (earliest version describing doxygen_add_docs, I've updated cmake_minimum_required to match): "So that relative input paths work as expected, by default the working directory of the Doxygen command will be the current source directory (i.e. CMAKE_CURRENT_SOURCE_DIR)." Likewise for the output directory: "Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that if the project provides its own value for this and it is a relative path, it will be converted to an absolute path relative to the current binary directory. This is necessary because doxygen will normally be run from a directory within the source tree so that relative source paths work as expected." --- CMakeLists.txt | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 62ff0a7559..02c1a2a4cc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,4 +1,4 @@ -cmake_minimum_required(VERSION 3.6) +cmake_minimum_required(VERSION 3.9) project(LAPACK) @@ -615,8 +615,8 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) set(DOXYGEN_PROJECT_BRIEF "LAPACK: Linear Algebra PACKage") set(DOXYGEN_PROJECT_NUMBER ${LAPACK_VERSION}) - set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/DOCS) - set(DOXYGEN_PROJECT_LOGO ${CMAKE_CURRENT_SOURCE_DIR}/DOCS/lapack.png) + set(DOXYGEN_OUTPUT_DIRECTORY DOCS) + set(DOXYGEN_PROJECT_LOGO DOCS/lapack.png) set(DOXYGEN_OPTIMIZE_FOR_FORTRAN YES) set(DOXYGEN_SOURCE_BROWSER YES) set(DOXYGEN_CREATE_SUBDIRS YES) @@ -656,13 +656,13 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) html # Doxygen INPUT = - ${PROJECT_SOURCE_DIR}/BLAS - ${PROJECT_SOURCE_DIR}/CBLAS - ${PROJECT_SOURCE_DIR}/SRC - ${PROJECT_SOURCE_DIR}/INSTALL - ${PROJECT_SOURCE_DIR}/TESTING - ${PROJECT_SOURCE_DIR}/DOCS/groups-usr.dox - ${PROJECT_SOURCE_DIR}/README.md + BLAS + CBLAS + SRC + INSTALL + TESTING + DOCS/groups-usr.dox + README.md COMMENT "Generating html LAPACK documentation (it will take some time... time to grab a coffee)" ) @@ -678,12 +678,12 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) man # Doxygen INPUT = - ${PROJECT_SOURCE_DIR}/BLAS - ${PROJECT_SOURCE_DIR}/CBLAS - ${PROJECT_SOURCE_DIR}/SRC - ${PROJECT_SOURCE_DIR}/INSTALL - ${PROJECT_SOURCE_DIR}/TESTING - ${PROJECT_SOURCE_DIR}/DOCS/groups-usr.dox + BLAS + CBLAS + SRC + INSTALL + TESTING + DOCS/groups-usr.dox COMMENT "Generating man LAPACK documentation" ) From 55d73a2ef29ac755c32c3cc16c2cc51564b6b0dc Mon Sep 17 00:00:00 2001 From: Kyle Guinn Date: Mon, 15 Jan 2024 23:11:04 -0600 Subject: [PATCH 6/6] Prevent html options from being applied to manpage generation When both BUILD_HTML_DOCUMENTATION and BUILD_MAN_DOCUMENTATION are ON, DOXYGEN_GENERATE_HTML was set to YES (and some other HTML-only variables were set) whenever Doxyfile.man was generated, and therefore `make man` would also populate DOCS/explore-html, but with less detail due to the other differences between Doxyfile.man and Doxyfile.html. --- CMakeLists.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 02c1a2a4cc..74384ec91d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -630,8 +630,6 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) set(DOXYGEN_INTERACTIVE_SVG YES) set(DOXYGEN_WARN_NO_PARAMDOC YES) set(DOXYGEN_WARN_LOGFILE doxygen_error) - set(DOXYGEN_GENERATE_HTML NO) - set(DOXYGEN_GENERATE_MAN NO) set(DOXYGEN_LAYOUT_FILE "DOCS/DoxygenLayout.xml") # Exclude functions that are duplicated, creating conflicts. @@ -646,12 +644,13 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) if (BUILD_HTML_DOCUMENTATION) set(DOXYGEN_GENERATE_HTML YES) - set(DOXYGEN_HTML_OUTPUT explore-html) - set(DOXYGEN_HTML_TIMESTAMP YES) + set(DOXYGEN_GENERATE_MAN NO) set(DOXYGEN_INLINE_SOURCES YES) set(DOXYGEN_CALL_GRAPH YES) set(DOXYGEN_CALLER_GRAPH YES) + set(DOXYGEN_HTML_OUTPUT explore-html) + set(DOXYGEN_HTML_TIMESTAMP YES) doxygen_add_docs( html @@ -666,14 +665,17 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) COMMENT "Generating html LAPACK documentation (it will take some time... time to grab a coffee)" ) + unset(DOXYGEN_HTML_OUTPUT) + unset(DOXYGEN_HTML_TIMESTAMP) endif() if (BUILD_MAN_DOCUMENTATION) + set(DOXYGEN_GENERATE_HTML NO) set(DOXYGEN_GENERATE_MAN YES) - set(DOXYGEN_MAN_LINKS YES) set(DOXYGEN_INLINE_SOURCES NO) set(DOXYGEN_CALL_GRAPH NO) set(DOXYGEN_CALLER_GRAPH NO) + set(DOXYGEN_MAN_LINKS YES) doxygen_add_docs( man @@ -687,6 +689,7 @@ if(BUILD_HTML_DOCUMENTATION OR BUILD_MAN_DOCUMENTATION) COMMENT "Generating man LAPACK documentation" ) + unset(DOXYGEN_MAN_LINKS) endif() endif()