a bunch of doc fixes (#11230) (#11237)

docs/doxyrest-config.lua

@@ -161,7 +161,7 @@ VERBATIM_TO_CODE_BLOCK = "cpp"
 --! reStructuredText (asterisks are used to mark **bold** or *italic* blocks).
 --!
 
-ESCAPE_ASTERISKS = true
+ESCAPE_ASTERISKS = false
 
 --!
 --! If the original doxy comments contain pipe characters ``|``, they have to be

docs/scripts/doxy_md_filter.py

@@ -127,7 +127,7 @@ class DoxyMDFilter:
         reference_links = set(re.findall(REFERENCE_LINKS_PATTERN, self.content))
         md_links = inline_links
         md_links.update(reference_links)
-        return md_links
+        return sorted(md_links, key=len, reverse=True)
 
 
 def get_label(file):

docs/scripts/prepare_xml.py

@@ -25,6 +25,8 @@ def prepare_xml(xml_dir: Path):
             if matches:
                 for match in matches:
                     contents = contents.replace(match, saxutils.escape(match))
+            # escape asterisks
+            contents = contents.replace('*', '\\*')
             contents = str.encode(contents)
             root = etree.fromstring(contents)
             anchors = root.xpath('//anchor')