Re-sync Doxyfile with CMake #978
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
QUIET defaults to NO, WARNINGS defaults to YES.
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.
Both have been present in DOCS/Doxyfile since that file was added.
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."
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.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #978 +/- ##
=======================================
Coverage 0.00% 0.00%
=======================================
Files 1930 1930
Lines 190421 190421
=======================================
Misses 190421 190421 ☔ View full report in Codecov by Sentry. |
langou
approved these changes
Jan 17, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I'm comparing DOCS/Doxyfile with build/Doxyfile.html that CMake is generating. There are a few minor differences (mostly things in DOCS/Doxyfile that have strayed from the default but don't really matter) and this PR patches up most of those differences.
The easiest comparison method I found was to first filter the files through
doxygen -x, usually with a command likediff <(doxygen -x DOCS/Doxyfile) <(doxygen -x build/Doxyfile.html).Additionally I found that if you use
-DBUILD_HTML_DOCUMENTATION=ONand-DBUILD_MAN_DOCUMENTATION=ONsimultaneously, some of the HTML-specific settings get carried over into build/Doxyfile.man, and thenmake mangenerates HTML as a side effect. This is also fixed.