Merge pull request #740 from ManifoldFR/topic/doxygen-mathjax-2025

Add support for MathJax 3, upgrade vendored MathJax to 3.2.2

.pre-commit-config.yaml

@@ -45,4 +45,4 @@ repos:
   hooks:
   - id: check-hooks-apply
   - id: check-useless-excludes
-exclude: \.js$
+exclude: (\.js$|^doxygen/MathJax/)

doxygen.cmake

@@ -1,4 +1,4 @@
-# Copyright (C) 2008-2023 LAAS-CNRS, JRL AIST-CNRS, INRIA.
+# 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
@@ -254,6 +254,7 @@ macro(_SETUP_DOXYGEN_CONFIG_FILE configfile)
     MATHJAX_RELPATH
     MATHJAX_EXTENSIONS
     MATHJAX_CODEFILE
+    MATHJAX_VERSION
     SEARCHENGINE
     SERVER_BASED_SEARCH
     EXTERNAL_SEARCH
@@ -397,6 +398,39 @@ macro(_set_if_undefined variable)
   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
 # ----------------------------
 #
@@ -442,6 +476,7 @@ macro(_SETUP_DOXYGEN_DEFAULT_OPTIONS)
   # ---------------------------------------------------------------------------
   _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
   # ---------------------------------------------------------------------------
@@ -591,6 +626,15 @@ macro(_SETUP_PROJECT_DOCUMENTATION)
         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.

doxygen/MathJax/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [numfocus] 
+custom: ['https://numfocus.org/donate-to-mathjax']

doxygen/MathJax/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,54 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Replace the text below with the details of the issue you are facing.  
+DO NOT simply erase the form and type a free-form response.**
+-----
+
+### Issue Summary
+
+A summary of the issue and the browser/OS environment in which it occurs. If
+suitable, include the steps required to reproduce the bug.
+
+### Steps to Reproduce:
+
+1. This is the first step
+2. This is the second step
+3. Further steps, etc.
+
+Any other information you want to share that is relevant to the issue
+being reported. Especially, why do you consider this to be a bug? What
+do you expect to happen instead?
+
+### Technical details:
+
+* MathJax Version: 3.2
+* Client OS: (e.g., Mac OS X 10.8.4)
+* Browser: (e.g., Chrome 29.0.1547.57)
+
+I am using the following MathJax configuration:
+
+``` js
+MathJax = {
+...
+};
+```
+
+and loading MathJax via
+
+``` html
+<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
+```
+
+### Supporting information:
+
+ * Please supply a link to a (live) minimal example page, when possible.
+ * If your issue is with the display of the mathematics produced by MathJax, include a screen snapshot that illustrates the problem, when possible.
+ * Check your browser console window for any error messages, and include them here.
+ * Include the MathJax configuration you are using, and the script tag that loads MathJax itself.

doxygen/MathJax/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

doxygen/MathJax/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+

doxygen/MathJax/.travis.yml

@@ -0,0 +1,17 @@
+dist: focal
+language: node_js
+node_js:
+  - stable
+sudo: false
+script:
+  - npm test
+branches:
+  only:
+  - "/^\\d+\\.\\d+/"
+deploy:
+  provider: npm
+  email: [email protected]
+  api_key:
+    secure: rdvJ27qbw4DZJl49NSf/ybkeHWNWnk2MajS8Y8bMKwI8RaDyEGcAm3frA+CfBw+YHWl71KRJlQHL69YgVwp1nMSzKrGOpwrbL3TMFrFMdBC6tJ30dX1HSvAg9eU5K12E5672MM8qkTwJdYXsvEcyYlzRR+sogR8jTWRl3APuAwY=
+  on:
+    tags: true