Improve Doxygen output even further

docs/DoxygenLayout.xml

@@ -5,7 +5,10 @@
 
   <!-- Navigation index tabs for HTML output -->
   <navindex>
+    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="user" visible="yes" url="_HEADING_" title="Installation and Changelog" />
     <tab type="user" visible="yes" url="@ref md_install" title="Install" />
+    <tab type="user" visible="yes" url="_HEADING_" title="API Reference" />
     <tab type="usergroup" visible="yes" url="@ref actions_group" title="Action" >
       <tab type="usergroup" visible="yes" url="actions__group.html#nested-classes" title="Classes" >
         <tab type="user" visible="yes" url="@ref libsemigroups::Action" title="Action" />
@@ -27,11 +30,12 @@
       <tab type="user" visible="yes" url="group__congruences__group.html#func-members" title="Functions" />
     </tab>
     <tab type="examples" visible="yes" title="" intro=""/>
+    <tab type="user" visible="yes" url="_HEADING_" title="Bibliography" />
     <tab type="user" visible="yes" url="@ref citelist" title="Bibliography" />
+    <tab type="user" visible="yes" url="_HEADING_" title="Further info" />
     <tab type="user" url="https://github.com/libsemigroups/libsemigroups" title="GitHub"/>
 
     <!--
-    <tab type="mainpage" visible="yes" title=""/>
     <tab type="pages" visible="no" title="" intro=""/>
     <tab type="namespaces" visible="no" title="">
       <tab type="namespacelist" visible="no" title="" intro=""/>

docs/custom.css

@@ -12,3 +12,9 @@
   width: 72px;
   height: 72px;
 }
+
+#nav-tree .label[role="heading"] {
+  text-transform: uppercase;
+  color: var(--primary-dark-color);
+  font-weight: 600;
+}

docs/fixup.py

@@ -4,18 +4,48 @@
 
 from typing import Callable
 from pprint import pformat
+from glob import glob
 import re
 
 
-def modify_in_place(filename: str, function: Callable[[str], tuple[str, bool]]) -> None:
+def modify_in_place(
+    filename: str, function: Callable[[str], tuple[str, bool]], warn: bool = True
+) -> bool:
     """Run a function over the contents of a file, modifying it in place."""
     with open(filename, "r") as in_file:
         data = in_file.read()
     data, success = function(data)
     if not success:
-        print(f"Warning: {function.__name__} failed to modify {filename}!")
+        if warn:
+            print(f"Warning: {function.__name__} failed to modify {filename}!")
+        return False
     with open(filename, "w") as out_file:
         out_file.write(data)
+    return True
+
+
+def modify_in_place_all_files(
+    filename_glob: str, function: Callable[[str], tuple[str, bool]], warn: bool = True
+) -> bool:
+    filenames = glob(filename_glob)
+    if len(filenames) == 0:
+        if warn:
+            print(
+                f"Warning: no files matched glob {filename_glob}, so {function.__name__} did not run!"
+            )
+        return False
+
+    all_fail = True
+    for filename in filenames:
+        success = modify_in_place(filename, function, warn=False)
+        if success:
+            all_fail = False
+
+    if all_fail and warn:
+        print(
+            f"Warning: {function.__name__} failed to modify any files matching {filename_glob}!"
+        )
+    return all_fail
 
 
 def fix_menu_1(data: str) -> tuple[str, bool]:
@@ -123,19 +153,9 @@ def fix_menu_3_part_1(data: str) -> tuple[str, bool]:
     tree = eval(match.group(1))
     assert len(tree) > 0, "Malformed tree"
     assert len(tree[0]) == 3, "Malformed tree"
-    index_children = tree[0][2]
-    new_index_children = []
-    for child in index_children:
-        assert len(child) == 3, "Malformed tree"
-        assert isinstance(child[1], str), "Malformed tree"
-        if child[1].split("#")[0] == "index.html":
-            new_index_children.append(child)
-        else:
-            tree.append(child)
-    tree[0][2] = new_index_children
-
+    assert tree[0][1] == "index.html", "Malformed tree"
     result, count = pattern.subn(
-        "const None = null;\nvar NAVTREE = \n" + pformat(tree) + ";\n", data
+        "const None = null;\nvar NAVTREE = \n" + pformat(tree[0][2]) + ";\n", data
     )
 
     return result, count > 0
@@ -175,39 +195,9 @@ def fix_menu_3_part_2(data: str) -> tuple[str, bool]:
         return data, False
 
     paths = eval(match.group(1))
-    if "pages.html" in paths:
-        # WARN: Not sure what the ramifications of deleting this are. Probably
-        # not an issue.
-        del paths["pages.html"]
-
-    bad_indices = []
-    for key, value in paths.items():
-        assert isinstance(key, str), "Malformed navigation index"
-        assert isinstance(value, list), "Malformed navigation index"
-        if key.split("#")[0] == "index.html":
-            if len(value) > 0:
-                assert value[0] >= 0, "Malformed navigation index"
-                bad_indices.append(value[0])
-            value.insert(0, 0)
-    bad_indices.sort()
-    k = max(bad_indices)
-
-    if k == 0:
-        # Everything is already fine
-        return data, True
-
-    if bad_indices != list(range(k + 1)):
-        # TODO: Implement this.
-        raise NotImplementedError(
-            "Can't handle case where index navtree indices are non contiguous",
-            (data, bad_indices, k),
-        )
-
-    for key, value in paths.items():
-        if key.split("#")[0] != "index.html":
-            if len(value) > 0:
-                assert value[0] > k, "Malformed navigation index"
-                value[0] -= k
+    for del_page in {"pages.html", "index.html"}:
+        if del_page in paths:
+            del paths[del_page]
 
     result, count = pattern.subn(
         "var NAVTREEINDEX0 = \n" + pformat(paths) + ";\n", data
@@ -253,9 +243,109 @@ def fix_menu_3_part_3(data: str) -> tuple[str, bool]:
     return result, count > 0
 
 
+def fix_menu_4(data: str) -> tuple[str, bool]:
+    """Add support for navmenu headings.
+
+    By default the every entry in the navmenu is a link. We would like to add support for navmenu headings.
+
+    This function fixes this issue by modifying the contents of `navtree.js`.
+
+    Parameters
+    ----------
+    data: str
+        The string corresponding to the source code to be modified.
+
+    Returns
+    -------
+    str
+        The modified source code.
+    bool
+        A boolean indicating if any changes were made.
+
+    Notes
+    -----
+    Does some rather esoteric modifications on `navtree.js`.
+    Should work for 1.7.2 <= Doxygen <= 1.10.0
+    """
+
+    regex = re.compile(
+        r'(?s:(var|const)\s*a\s*=\s*document.createElement\(\s*"a"\s*\);(.*?)return\s*node;)'
+    )
+    match = regex.search(data)
+    if match is None:
+        return data, False
+    inner_data = match.group(2)
+    # Check if we are in older version of Doxygen
+    if re.match(r"node.childrenUL\s*=\s*null;", inner_data) is None:
+        # New version >= 1.10.0
+        result, count = regex.subn(
+            r"""if (link == "_HEADING_") {
+  node.labelSpan.role = "heading";
+  node.labelSpan.appendChild(node.label);
+  po.getChildrenUL().appendChild(node.li);
+} else {
+  \1 a = document.createElement("a");
+  \2
+}
+return node;""",
+            data,
+        )
+    else:
+        # Old version < 1.10.0
+        regex = re.compile(
+            r'(?s:(var|const)\s*a\s*=\s*document.createElement\(\s*"a"\s*\);(.*?)node.childrenUL\s*=\s*null;)'
+        )
+        result, count = regex.subn(
+            r"""if (link == "_HEADING_") {
+  node.labelSpan.role = "heading";
+  node.labelSpan.appendChild(node.label);
+} else {
+  \1 a = document.createElement("a");
+  \2
+}
+node.childrenUL = null;""",
+            data,
+        )
+
+    return result, count > 0
+
+
+def fix_pages_1(data: str) -> tuple[str, bool]:
+    """Remove detailed description header.
+
+    The "Detailed Description" header looks out of place. This function fixes
+    the issue by modifying the contents of `*.html` files.
+
+    Parameters
+    ----------
+    data: str
+        The string corresponding to the source code to be modified.
+
+    Returns
+    -------
+    str
+        The modified source code.
+    bool
+        A boolean indicating if any changes were made.
+
+
+    Notes
+    -----
+    Fixed by deleting the `<h2 class="groupheader">Detailed Description</h2>` element.
+    """
+    result, count = re.subn(
+        r'(?s:<h2\s+class\s*=\s*"groupheader"\s*>\s*Detailed\s*Description\s*</h2>)',
+        r"",
+        data,
+    )
+    return result, count > 0
+
+
 if __name__ == "__main__":
     modify_in_place("./html/navtree.js", fix_menu_1)
     modify_in_place("./html/navtree.js", fix_menu_2)
     modify_in_place("./html/navtreedata.js", fix_menu_3_part_1)
     modify_in_place("./html/navtreeindex0.js", fix_menu_3_part_2)
     modify_in_place("./html/navtree.js", fix_menu_3_part_3)
+    modify_in_place("./html/navtree.js", fix_menu_4)
+    modify_in_place_all_files("./html/*.html", fix_pages_1)