From febf7c41881719783d233d4364261558ca612f9f Mon Sep 17 00:00:00 2001
From: "Antoine Vandevenne (anv)" <anv@odoo.com>
Date: Tue, 3 Jan 2023 14:12:48 +0000
Subject: [PATCH] [IMP] odoo_theme: tweak the HTML structure of TOC entries

task-3046383

X-original-commit: 877d1de3c2240453cbbadb1dbfc33b51c985a044
Part-of: odoo/documentation#4114
---
 extensions/custom_admonitions/__init__.py |  8 +--
 extensions/odoo_theme/static/js/utils.js  | 87 +++++++++++++----------
 2 files changed, 55 insertions(+), 40 deletions(-)

diff --git a/extensions/custom_admonitions/__init__.py b/extensions/custom_admonitions/__init__.py
index 153c8c0a0..81cc40436 100644
--- a/extensions/custom_admonitions/__init__.py
+++ b/extensions/custom_admonitions/__init__.py
@@ -32,15 +32,15 @@ class Dfn(SphinxRole):
         sphinx.nodes.* class to prevent automatically setting the name of the node as class (e.g.,
         "container") on the element.
         """
-        outer_span = Span(classes=['dfn'])
-        inner_span = Span()
+        outer_span = DfnSpan(classes=['dfn'])
+        inner_span = DfnSpan()
         outer_span.append(inner_span)
         text = nodes.Text(self.text)
         inner_span.append(text)
         return [outer_span], []
 
 
-class Span(nodes.General, nodes.Element):
+class DfnSpan(nodes.General, nodes.Element):
 
     @staticmethod
     def visit(translator, node):
@@ -63,7 +63,7 @@ def setup(app):
         lambda self, node: self.depart_admonition(node),
     ))
     app.add_role('dfn', Dfn(), override=True)
-    app.add_node(Span, html=(Span.visit, Span.depart))
+    app.add_node(DfnSpan, html=(DfnSpan.visit, DfnSpan.depart))
 
     return {
         'parallel_read_safe': True,
diff --git a/extensions/odoo_theme/static/js/utils.js b/extensions/odoo_theme/static/js/utils.js
index 0d6a6020c..d27facd55 100644
--- a/extensions/odoo_theme/static/js/utils.js
+++ b/extensions/odoo_theme/static/js/utils.js
@@ -4,63 +4,78 @@ let tocEntryListId = 0; // Used to generate IDs of toc entry lists for both the
  * Update the provided TOC to allow collapsing its entries with Bootstrap's accordion.
  *
  * The typical structure of a TOC menu is a follows:
- * <ul><li>
- *     <a href="#"/>
- *     <ul>
- *         <li><a href="#heading_without_child"/></li>
- *         <li>
- *             <a href="#heading_with_children"/>
- *             <ul>...</ul>
- *         </li>
- *     </ul>
- * </li></ul>
+ * <ul>
+ *     <li>
+ *         <a name="heading_without_children" href="something.html">Something</a>
+ *     </li>
+ *     <li>
+ *         <a name="non-clickable_heading_with_children" href="#">Something</a>
+ *         <ul>...</ul>
+ *     </li>
+ *     <li>
+ *         <a name="clickable_heading_with_children" href="something.html">Something</a>
+ *         <ul>...</ul>
+ *     </li>
+ * </ul>
  *
  * Since a <ul> is always preceded by a <a>, and since we only need to make change to <a>
  * elements followed by a <ul>, we simply loop on <ul> elements to access all parts of the DOM
  * that need to be modified.
  *
  * The final structure must look like this:
- * <ul><li>
- *     <!-- Only <a> element with empty href must expand/collapse on click -->
- *     <a href="#" data-bs-target="#o_target_{id}>" data-bs-toggle="collapse"/>
- *     <ul>
- *         <li><a href="#heading_without_child"/></li>
- *         <li>
- *             <div class="o_toc_entry_wrapper">
- *                 <i class="i-chevron-right" data-bs-target="#o_target_{id}" data-bs-toggle="collapse"/>
- *                 <a href="#heading_with_children"/>
- *             </div>
- *             <ul id="o_target_{id}" class="collapse">...</ul>
- *         </li>
- *     </ul>
- * </li></ul>
+ * <ul>
+ *     <!-- Unchanged -->
+ *     <li>
+ *         <a name="heading_without_children" href="something.html">Something</a>
+ *     </li>
+ *     <!-- Create a <div>; append <i> and <a> to <div>; set BS target on <a> and <i>; set id on <ul> -->
+ *     <li>
+ *         <div class="o_toc_entry_wrapper">
+ *             <i class="i-chevron-right" data-bs-target="#o_target_123" data-bs-toggle="collapse"/>
+ *             <a name="non-clickable_heading_with_children" href="#" data-bs-target="#o_target_123>" data-bs-toggle="collapse">Something</a>
+ *         </div>
+ *         <ul id="o_target_123" class="collapse">...</ul>
+ *     </li>
+ *     <!-- Create a <div>; append <i> and <a> to <div>; set BS target on only <i> to let the <a> redirect; set id on <ul> -->
+ *     <li>
+ *         <div class="o_toc_entry_wrapper">
+ *             <i class="i-chevron-right" data-bs-target="#o_target_456" data-bs-toggle="collapse"/>
+ *             <a name="clickable_heading_with_children" href="something.html">Something</a>
+ *         </div>
+ *         <ul id="o_target_456" class="collapse">...</ul>
+ *     </li>
+ *</ul>
  *
- * @param {HTMLElement} tocElement - The element containing the TOC
+ * @param {HTMLElement} tocElement - The element containing the TOC.
  */
 const _prepareAccordion = (tocElement) => {
-    // Start at the second TOC entry list (<ul>) to avoid collapsing the entire TOC
+    // Start at the second TOC entry list (<ul>) to avoid collapsing the entire TOC.
     const tocRoot = tocElement.querySelector('ul');
     tocRoot.querySelectorAll('ul').forEach(tocEntryList => {
-        // Modify the <ul> element
+        // Modify the <ul> element.
         tocEntryList.id = `o_target_${tocEntryListId++}`;
         tocEntryList.classList.add('collapse');
-        // Create and configure an <i> element
-        const arrowButton = document.createElement('I');
-        arrowButton.setAttribute('data-bs-target', `#${tocEntryList.id}`);
-        arrowButton.setAttribute('data-bs-toggle', 'collapse');
-        arrowButton.classList.add('i-chevron-right');
-        // Modify the <a> element (only if it has no href, otherwise let the redirection happen)
+
+        // Modify the <a> element only if it has no href; otherwise, let the redirection happen.
         const relatedHeadingRef = tocEntryList.previousSibling;
         if (relatedHeadingRef.getAttribute('href') === '#') {
             relatedHeadingRef.setAttribute('data-bs-target', `#${tocEntryList.id}`);
             relatedHeadingRef.setAttribute('data-bs-toggle', 'collapse');
         }
-        // Create a <div> element
+
+        // Create and configure a <div> element.
         const tocEntryWrapper = document.createElement('DIV');
         tocEntryWrapper.classList.add('o_toc_entry_wrapper');
-        // Insert the <i> and <a> elements inside the <div> and prepend the <div> to the <ul>
+        tocEntryList.parentElement.insertBefore(tocEntryWrapper, tocEntryList);
+
+        // Create and configure an <i> element.
+        const arrowButton = document.createElement('I');
+        arrowButton.setAttribute('data-bs-target', `#${tocEntryList.id}`);
+        arrowButton.setAttribute('data-bs-toggle', 'collapse');
+        arrowButton.classList.add('i-chevron-right');
+
+        // Insert the <i> and <a> elements inside the <div>.
         tocEntryWrapper.append(arrowButton, relatedHeadingRef);
-        tocEntryList.parentNode.insertBefore(tocEntryWrapper, tocEntryList);
     });
 };