build: move to doxygen 1.15.0 by default

Author: TendTo

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
     branches: [main]
 
 env:
-  DEFAULT_DOXYGEN_VERSION: "1.14.0"
+  DEFAULT_DOXYGEN_VERSION: "1.15.0"
 
 jobs:
   tests:

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0]
+
+### Changed
+
+- Default doxygen version is now `1.15.0`
+
 ## [2.5.1]
 
 ### Changed

README.md

@@ -44,7 +44,7 @@ doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_ex
 use_repo(doxygen_extension, "doxygen")
 ```
 
-The extension will create a default configuration for all platforms with the version `1.14.0` of Doxygen.
+The extension will create a default configuration for all platforms with the version `1.15.0` of Doxygen.
 You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_, _mac-arm_, _linux_ and _linux-arm_.
 
 ```bzl

docs/doxygen_doc.md

@@ -37,14 +37,15 @@ doxygen(<a href="#doxygen-name">name</a>, <a href="#doxygen-srcs">srcs</a>, <a h
         <a href="#doxygen-qt_autobrief">qt_autobrief</a>, <a href="#doxygen-multiline_cpp_is_brief">multiline_cpp_is_brief</a>, <a href="#doxygen-python_docstring">python_docstring</a>, <a href="#doxygen-inherit_docs">inherit_docs</a>, <a href="#doxygen-separate_member_pages">separate_member_pages</a>,
         <a href="#doxygen-tab_size">tab_size</a>, <a href="#doxygen-aliases">aliases</a>, <a href="#doxygen-optimize_output_for_c">optimize_output_for_c</a>, <a href="#doxygen-optimize_output_java">optimize_output_java</a>, <a href="#doxygen-optimize_for_fortran">optimize_for_fortran</a>,
         <a href="#doxygen-optimize_output_vhdl">optimize_output_vhdl</a>, <a href="#doxygen-optimize_output_slice">optimize_output_slice</a>, <a href="#doxygen-extension_mapping">extension_mapping</a>, <a href="#doxygen-markdown_support">markdown_support</a>,
-        <a href="#doxygen-toc_include_headings">toc_include_headings</a>, <a href="#doxygen-markdown_id_style">markdown_id_style</a>, <a href="#doxygen-autolink_support">autolink_support</a>, <a href="#doxygen-autolink_ignore_words">autolink_ignore_words</a>,
-        <a href="#doxygen-builtin_stl_support">builtin_stl_support</a>, <a href="#doxygen-cpp_cli_support">cpp_cli_support</a>, <a href="#doxygen-sip_support">sip_support</a>, <a href="#doxygen-idl_property_support">idl_property_support</a>, <a href="#doxygen-distribute_group_doc">distribute_group_doc</a>,
-        <a href="#doxygen-group_nested_compounds">group_nested_compounds</a>, <a href="#doxygen-subgrouping">subgrouping</a>, <a href="#doxygen-inline_grouped_classes">inline_grouped_classes</a>, <a href="#doxygen-inline_simple_structs">inline_simple_structs</a>,
-        <a href="#doxygen-typedef_hides_struct">typedef_hides_struct</a>, <a href="#doxygen-lookup_cache_size">lookup_cache_size</a>, <a href="#doxygen-num_proc_threads">num_proc_threads</a>, <a href="#doxygen-timestamp">timestamp</a>, <a href="#doxygen-extract_all">extract_all</a>,
-        <a href="#doxygen-extract_private">extract_private</a>, <a href="#doxygen-extract_priv_virtual">extract_priv_virtual</a>, <a href="#doxygen-extract_package">extract_package</a>, <a href="#doxygen-extract_static">extract_static</a>, <a href="#doxygen-extract_local_classes">extract_local_classes</a>,
-        <a href="#doxygen-extract_local_methods">extract_local_methods</a>, <a href="#doxygen-extract_anon_nspaces">extract_anon_nspaces</a>, <a href="#doxygen-resolve_unnamed_params">resolve_unnamed_params</a>, <a href="#doxygen-hide_undoc_members">hide_undoc_members</a>,
-        <a href="#doxygen-hide_undoc_classes">hide_undoc_classes</a>, <a href="#doxygen-hide_undoc_namespaces">hide_undoc_namespaces</a>, <a href="#doxygen-hide_friend_compounds">hide_friend_compounds</a>, <a href="#doxygen-hide_in_body_docs">hide_in_body_docs</a>,
-        <a href="#doxygen-internal_docs">internal_docs</a>, <a href="#doxygen-case_sense_names">case_sense_names</a>, <a href="#doxygen-hide_scope_names">hide_scope_names</a>, <a href="#doxygen-hide_compound_reference">hide_compound_reference</a>, <a href="#doxygen-show_headerfile">show_headerfile</a>,
+        <a href="#doxygen-markdown_strict">markdown_strict</a>, <a href="#doxygen-toc_include_headings">toc_include_headings</a>, <a href="#doxygen-markdown_id_style">markdown_id_style</a>, <a href="#doxygen-autolink_support">autolink_support</a>,
+        <a href="#doxygen-autolink_ignore_words">autolink_ignore_words</a>, <a href="#doxygen-builtin_stl_support">builtin_stl_support</a>, <a href="#doxygen-cpp_cli_support">cpp_cli_support</a>, <a href="#doxygen-sip_support">sip_support</a>,
+        <a href="#doxygen-idl_property_support">idl_property_support</a>, <a href="#doxygen-distribute_group_doc">distribute_group_doc</a>, <a href="#doxygen-group_nested_compounds">group_nested_compounds</a>, <a href="#doxygen-subgrouping">subgrouping</a>,
+        <a href="#doxygen-inline_grouped_classes">inline_grouped_classes</a>, <a href="#doxygen-inline_simple_structs">inline_simple_structs</a>, <a href="#doxygen-typedef_hides_struct">typedef_hides_struct</a>, <a href="#doxygen-lookup_cache_size">lookup_cache_size</a>,
+        <a href="#doxygen-num_proc_threads">num_proc_threads</a>, <a href="#doxygen-timestamp">timestamp</a>, <a href="#doxygen-extract_all">extract_all</a>, <a href="#doxygen-extract_private">extract_private</a>, <a href="#doxygen-extract_priv_virtual">extract_priv_virtual</a>,
+        <a href="#doxygen-extract_package">extract_package</a>, <a href="#doxygen-extract_static">extract_static</a>, <a href="#doxygen-extract_local_classes">extract_local_classes</a>, <a href="#doxygen-extract_local_methods">extract_local_methods</a>,
+        <a href="#doxygen-extract_anon_nspaces">extract_anon_nspaces</a>, <a href="#doxygen-resolve_unnamed_params">resolve_unnamed_params</a>, <a href="#doxygen-hide_undoc_members">hide_undoc_members</a>, <a href="#doxygen-hide_undoc_classes">hide_undoc_classes</a>,
+        <a href="#doxygen-hide_undoc_namespaces">hide_undoc_namespaces</a>, <a href="#doxygen-hide_friend_compounds">hide_friend_compounds</a>, <a href="#doxygen-hide_in_body_docs">hide_in_body_docs</a>, <a href="#doxygen-internal_docs">internal_docs</a>,
+        <a href="#doxygen-case_sense_names">case_sense_names</a>, <a href="#doxygen-hide_scope_names">hide_scope_names</a>, <a href="#doxygen-hide_compound_reference">hide_compound_reference</a>, <a href="#doxygen-show_headerfile">show_headerfile</a>,
         <a href="#doxygen-show_include_files">show_include_files</a>, <a href="#doxygen-show_grouped_memb_inc">show_grouped_memb_inc</a>, <a href="#doxygen-force_local_includes">force_local_includes</a>, <a href="#doxygen-inline_info">inline_info</a>,
         <a href="#doxygen-sort_member_docs">sort_member_docs</a>, <a href="#doxygen-sort_brief_docs">sort_brief_docs</a>, <a href="#doxygen-sort_members_ctors_1st">sort_members_ctors_1st</a>, <a href="#doxygen-sort_group_names">sort_group_names</a>,
         <a href="#doxygen-sort_by_scope_name">sort_by_scope_name</a>, <a href="#doxygen-strict_proto_matching">strict_proto_matching</a>, <a href="#doxygen-generate_todolist">generate_todolist</a>, <a href="#doxygen-generate_testlist">generate_testlist</a>,
@@ -310,6 +311,7 @@ doxygen(
 | <a id="doxygen-optimize_output_slice"></a>optimize_output_slice |  Set the `optimize_output_slice` tag to `True` if your project consists of Slice sources only.   |  `None` |
 | <a id="doxygen-extension_mapping"></a>extension_mapping |  Doxygen selects the parser to use depending on the extension of the files it parses.   |  `None` |
 | <a id="doxygen-markdown_support"></a>markdown_support |  If the `markdown_support` tag is enabled then Doxygen pre-processes all comments according to the Markdown format, which allows for more readable documentation.   |  `None` |
+| <a id="doxygen-markdown_strict"></a>markdown_strict |  If the markdown_strict tag is enabled then Doxygen treats text in comments as Markdown formatted also in cases where Doxygen's native markup format conflicts with that of Markdown.   |  `None` |
 | <a id="doxygen-toc_include_headings"></a>toc_include_headings |  When the `toc_include_headings` tag is set to a non-zero value, all headings up to that level are automatically included in the table of contents, even if they do not have an id attribute.   |  `None` |
 | <a id="doxygen-markdown_id_style"></a>markdown_id_style |  The `markdown_id_style` tag can be used to specify the algorithm used to generate identifiers for the Markdown headings.   |  `None` |
 | <a id="doxygen-autolink_support"></a>autolink_support |  When enabled Doxygen tries to link words that correspond to documented classes, or namespaces to their corresponding documentation.   |  `None` |

docs/extensions_doc.md

@@ -128,7 +128,7 @@ The resulting repository will have the following targets:
 - `@doxygen//:doxygen.bzl`, containing the doxygen macro used to generate the documentation.
 - `@doxygen//:Doxyfile.template`, default Doxyfile template used to generate the Doxyfile.
 
-The extension will create a default configuration for all platforms with the version `1.14.0` of Doxygen.
+The extension will create a default configuration for all platforms with the version `1.15.0` of Doxygen.
 You can override this value with a custom one for each supported platform, i.e. _windows_, _mac_, _mac-arm_, _linux_ and _linux-arm_.
 
 ```bzl

doxygen/Doxyfile.template

@@ -1,4 +1,4 @@
-# Doxyfile 1.14.0
+# Doxyfile 1.15.0
 
 # This file describes the settings to be used by the documentation system
 # Doxygen (www.doxygen.org) for a project.
@@ -361,6 +361,20 @@ EXTENSION_MAPPING      =
 
 MARKDOWN_SUPPORT       = YES
 
+# If the MARKDOWN_STRICT tag is enabled then Doxygen treats text in comments as
+# Markdown formatted also in cases where Doxygen's native markup format
+# conflicts with that of Markdown. This is only relevant in cases where
+# backticks are used. Doxygen's native markup style allows a single quote to end
+# a text fragment started with a backtick and then treat it as a piece of quoted
+# text, whereas in Markdown such text fragment is treated as verbatim and only
+# ends when a second matching backtick is found. Also, Doxygen's native markup
+# format requires double quotes to be escaped when they appear in a backtick
+# section, whereas this is not needed for Markdown.
+# The default value is: YES.
+# This tag requires that the tag MARKDOWN_SUPPORT is set to YES.
+
+MARKDOWN_STRICT        = YES
+
 # When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up
 # to that level are automatically included in the table of contents, even if
 # they do not have an id attribute.
@@ -510,7 +524,7 @@ LOOKUP_CACHE_SIZE      = 0
 # which effectively disables parallel processing. Please report any issues you
 # encounter. Generating dot graphs in parallel is controlled by the
 # DOT_NUM_THREADS setting.
-# Minimum value: 0, maximum value: 32, default value: 1.
+# Minimum value: 0, maximum value: 512, default value: 1.
 
 NUM_PROC_THREADS       = 1
 
@@ -1908,7 +1922,7 @@ USE_MATHJAX            = NO
 # regards to the different settings, so it is possible that also other MathJax
 # settings have to be changed when switching between the different MathJax
 # versions.
-# Possible values are: MathJax_2 and MathJax_3.
+# Possible values are: MathJax_2, MathJax_3 and MathJax_4.
 # The default value is: MathJax_2.
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
@@ -1917,9 +1931,10 @@ MATHJAX_VERSION        = MathJax_2
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. For more details about the output format see MathJax
 # version 2 (see:
-# http://docs.mathjax.org/en/v2.7-latest/output.html) and MathJax version 3
+# https://docs.mathjax.org/en/v2.7/output.html), MathJax version 3 (see:
+# https://docs.mathjax.org/en/v3.2/output/index.html) and MathJax version 4
 # (see:
-# http://docs.mathjax.org/en/latest/web/components/output.html).
+# https://docs.mathjax.org/en/v4.0/output/index.htm).
 # Possible values are: HTML-CSS (which is slower, but has the best
 # compatibility. This is the name for Mathjax version 2, for MathJax version 3
 # this will be translated into chtml), NativeMML (i.e. MathML. Only supported
@@ -1932,36 +1947,50 @@ MATHJAX_VERSION        = MathJax_2
 MATHJAX_FORMAT         = HTML-CSS
 
 # When MathJax is enabled you need to specify the location relative to the HTML
-# output directory using the MATHJAX_RELPATH option. The destination directory
-# should contain the MathJax.js script. For instance, if the mathjax directory
-# is located at the same level as the HTML output directory, then
-# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax
-# Content Delivery Network so you can quickly see the result without installing
-# MathJax. However, it is strongly recommended to install a local copy of
-# MathJax from https://www.mathjax.org before deployment. The default value is:
+# output directory using the MATHJAX_RELPATH option. For Mathjax version 2 the
+# destination directory should contain the MathJax.js script. For instance, if
+# the mathjax directory is located at the same level as the HTML output
+# directory, then MATHJAX_RELPATH should be ../mathjax.s For Mathjax versions 3
+# and 4 the destination directory should contain the tex-<format>.js script
+# (where <format> is either chtml or svg). The default value points to the
+# MathJax Content Delivery Network so you can quickly see the result without
+# installing MathJax. However, it is strongly recommended to install a local
+# copy of MathJax from https://www.mathjax.org before deployment. The default
+# value is:
 # - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2
 # - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3
+# - in case of MathJax version 4: https://cdn.jsdelivr.net/npm/mathjax@4
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
 MATHJAX_RELPATH        =
 
 # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax
 # extension names that should be enabled during MathJax rendering. For example
-# for MathJax version 2 (see
-# https://docs.mathjax.org/en/v2.7-latest/tex.html#tex-and-latex-extensions):
+# for MathJax version 2 (see https://docs.mathjax.org/en/v2.7/tex.html):
 # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
 # For example for MathJax version 3 (see
-# http://docs.mathjax.org/en/latest/input/tex/extensions/index.html):
+# https://docs.mathjax.org/en/v3.2/input/tex/extensions/):
 # MATHJAX_EXTENSIONS = ams
+# For example for MathJax version 4 (see
+# https://docs.mathjax.org/en/v4.0/input/tex/extensions/):
+# MATHJAX_EXTENSIONS = units
+# Note that for Mathjax version 4 quite a few extensions are already
+# automatically loaded. To disable a package in Mathjax version 4 one can use
+# the package name prepended with a minus sign (- like MATHJAX_EXTENSIONS +=
+# -textmacros)
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
 MATHJAX_EXTENSIONS     =
 
 # The MATHJAX_CODEFILE tag can be used to specify a file with JavaScript pieces
-# of code that will be used on startup of the MathJax code. See the MathJax site
-# (see:
-# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an
-# example see the documentation.
+# of code that will be used on startup of the MathJax code. See the Mathjax site
+# for more details:
+# - MathJax version 2 (see:
+# https://docs.mathjax.org/en/v2.7/)
+# - MathJax version 3 (see:
+# https://docs.mathjax.org/en/v3.2/)
+# - MathJax version 4 (see:
+# https://docs.mathjax.org/en/v4.0/) For an example see the documentation.
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
 MATHJAX_CODEFILE       =
@@ -2622,7 +2651,7 @@ HAVE_DOT               = NO
 # processors available in the system. You can set it explicitly to a value
 # larger than 0 to get control over the balance between CPU load and processing
 # speed.
-# Minimum value: 0, maximum value: 32, default value: 0.
+# Minimum value: 0, maximum value: 512, default value: 0.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 DOT_NUM_THREADS        = 0

doxygen/doxygen.bzl

@@ -249,6 +249,7 @@ def doxygen(
         optimize_output_slice = None,
         extension_mapping = None,
         markdown_support = None,
+        markdown_strict = None,
         toc_include_headings = None,
         markdown_id_style = None,
         autolink_support = None,
@@ -746,6 +747,7 @@ def doxygen(
         optimize_output_slice: Set the `optimize_output_slice` tag to `True` if your project consists of Slice sources only.
         extension_mapping: Doxygen selects the parser to use depending on the extension of the files it parses.
         markdown_support: If the `markdown_support` tag is enabled then Doxygen pre-processes all comments according to the Markdown format, which allows for more readable documentation.
+        markdown_strict: If the markdown_strict tag is enabled then Doxygen treats text in comments as Markdown formatted also in cases where Doxygen's native markup format conflicts with that of Markdown.
         toc_include_headings: When the `toc_include_headings` tag is set to a non-zero value, all headings up to that level are automatically included in the table of contents, even if they do not have an id attribute.
         markdown_id_style: The `markdown_id_style` tag can be used to specify the algorithm used to generate identifiers for the Markdown headings.
         autolink_support: When enabled Doxygen tries to link words that correspond to documented classes, or namespaces to their corresponding documentation.
@@ -1058,6 +1060,7 @@ def doxygen(
     _add_generic_configuration(configurations, "OPTIMIZE_OUTPUT_SLICE", optimize_output_slice)
     _add_generic_configuration(configurations, "EXTENSION_MAPPING", extension_mapping)
     _add_generic_configuration(configurations, "MARKDOWN_SUPPORT", markdown_support)
+    _add_generic_configuration(configurations, "MARKDOWN_STRICT", markdown_strict)
     _add_generic_configuration(configurations, "TOC_INCLUDE_HEADINGS", toc_include_headings)
     _add_generic_configuration(configurations, "MARKDOWN_ID_STYLE", markdown_id_style)
     _add_generic_configuration(configurations, "AUTOLINK_SUPPORT", autolink_support)

examples/executable/main.cpp

@@ -31,7 +31,7 @@ int main(int argc, char* argv[]) {
           "    <p>Output directory: "
        << out_path
        << "</p>\n"
-          "    <p>Generated by a custom executable mimicking Doxygen 1.14.0.</p>\n"
+          "    <p>Generated by a custom executable mimicking Doxygen 1.15.0.</p>\n"
           "</body>\n"
           "</html>\n";
   file.close();