Refactor navbar generating function (#1780)

Refactor navbar generating function.

This should fix #1773 (once fininished)

It tries to split the function into two parts: one that wrangle the
data,  one that generate html.

The generating the data part should be cacheable, while the other can be
made more flexible to be reusable in different part of the theme
(typically generating or not dropdowns in the sidebar or navbar).
---------

Co-authored-by: Daniel McCloy <[email protected]>

src/pydata_sphinx_theme/toctree.py

@@ -1,7 +1,9 @@
 """Methods to build the toctree used in the html pages."""
 
+from dataclasses import dataclass
 from functools import cache
 from itertools import count
+from textwrap import dedent
 from typing import Iterator, List, Tuple, Union
 from urllib.parse import urlparse
 
@@ -51,6 +53,16 @@ def _get_ancestor_pagename(app: Sphinx, pagename: str, startdepth: int) -> str:
     return out, toctree
 
 
+@dataclass
+class LinkInfo:
+    """Dataclass to generate toctree data."""
+
+    is_current: bool
+    href: str
+    title: str
+    is_external: bool
+
+
 def add_toctree_functions(
     app: Sphinx, pagename: str, templatename: str, context, doctree
 ) -> None:
@@ -101,28 +113,13 @@ def unique_html_id(base_id: str):
         return next(get_or_create_id_generator(base_id))
 
     @cache
-    def _generate_header_nav_before_dropdown(
-        n_links_before_dropdown,
-    ) -> Tuple[str, List[str]]:
-        """Return html for navbar and dropdown.
+    def _generate_nav_info() -> List[LinkInfo]:
+        """Generate informations necessary to generate nav.
 
-        .. warning::
-
-            Private helper function, do not call this directly.
-
-        Given the number of links before the dropdown, return the html for the navbar,
-        as well as the list of links to put in a dropdown.
-
-        Returns:
-            - HTML str for the navbar
-            - list of HTML str for the dropdown
+        Instead of messing with html later, having this as a util function
+        should make it slightly easier to generate different html snippet for
+        sidebar or navbar.
         """
-        try:
-            n_links_before_dropdown = int(n_links_before_dropdown)
-        except Exception:
-            raise ValueError(
-                f"n_links_before_dropdown is not an int: {n_links_before_dropdown}"
-            )
         toctree = TocTree(app.env)
 
         # Find the active header navigation item so we decide whether to highlight
@@ -133,22 +130,23 @@ def _generate_header_nav_before_dropdown(
             # NOTE: `env.toctree_includes` is a dict mapping pagenames to any (possibly
             # hidden) TocTree directives on that page (i.e., the "child" pages nested
             # under `pagename`).
-            active_header_page = [
-                *_get_toctree_ancestors(app.env.toctree_includes, pagename)
-            ]
+            header_pages = [*_get_toctree_ancestors(app.env.toctree_includes, pagename)]
         else:
-            active_header_page = toctree.get_toctree_ancestors(pagename)
-        if active_header_page:
+            header_pages = toctree.get_toctree_ancestors(pagename)
+        if header_pages:
             # The final list item will be the top-most ancestor
-            active_header_page = active_header_page[-1]
+            active_header_page = header_pages[-1]
+        else:
+            active_header_page = None
 
         # NOTE: `env.tocs` is a dict mapping pagenames to hierarchical bullet-lists
         # ("nodetrees" in Sphinx parlance) of in-page headings (including `toctree::`
         # directives). Thus the `tocs` of `root_doc` yields the top-level pages that sit
         # just below the root of our site
         root_toc = app.env.tocs[app.config.root_doc]
 
-        links_html = []
+        links_data = []
+
         # Iterate through each node in the root document toc.
         # Grab the toctree pages and find the relative link + title.
         for toc in traverse_or_findall(root_toc, TocTreeNodeClass):
@@ -159,7 +157,6 @@ def _generate_header_nav_before_dropdown(
                 page = toc.attributes["parent"] if page == "self" else page
 
                 # If this is the active ancestor page, add a class so we highlight it
-                current = "current active" if page == active_header_page else ""
 
                 # sanitize page title for use in the html output if needed
                 if title is None:
@@ -176,30 +173,69 @@ def _generate_header_nav_before_dropdown(
                 # If it's an absolute one then we use the external class and
                 # the complete url.
                 is_absolute = bool(urlparse(page).netloc)
-                link_status = "nav-external" if is_absolute else "nav-internal"
                 link_href = page if is_absolute else context["pathto"](page)
 
-                # create the html output
-                links_html.append(
-                    f"""
-                    <li class="nav-item pst-header-nav-item {current}">
-                      <a class="nav-link {link_status}" href="{link_href}">
-                        {title}
-                      </a>
-                    </li>
-                """
+                links_data.append(
+                    LinkInfo(
+                        is_current=(page == active_header_page),
+                        href=link_href,
+                        title=title,
+                        is_external=is_absolute,
+                    )
                 )
 
         # Add external links defined in configuration as sibling list items
         for external_link in context["theme_external_links"]:
+            links_data.append(
+                LinkInfo(
+                    is_current=False,
+                    href=external_link["url"],
+                    title=external_link["name"],
+                    is_external=True,
+                )
+            )
+
+        return links_data
+
+    @cache
+    def _generate_header_nav_before_dropdown(
+        n_links_before_dropdown,
+    ) -> Tuple[str, List[str]]:
+        """Return html for navbar and dropdown.
+
+        Given the number of links before the dropdown, return the html for the navbar,
+        as well as the list of links to put in a dropdown.
+
+        Returns:
+            - HTML str for the navbar
+            - list of HTML str for the dropdown
+        """
+        try:
+            n_links_before_dropdown = int(n_links_before_dropdown)
+        except Exception:
+            raise ValueError(
+                f"n_links_before_dropdown is not an int: {n_links_before_dropdown}"
+            )
+        links_data = _generate_nav_info()
+
+        links_html = []
+        boilerplate = """
+            <li class="nav-item pst-header-nav-item{active}">
+              <a class="nav-link nav-{ext_int}" href="{href}">
+                {title}
+              </a>
+            </li>
+            """
+        for link in links_data:
             links_html.append(
-                f"""
-                <li class="nav-item pst-header-nav-item">
-                  <a class="nav-link nav-external" href="{ external_link["url"] }">
-                    { external_link["name"] }
-                  </a>
-                </li>
-                """
+                dedent(
+                    boilerplate.format(
+                        active=" current active" if link.is_current else "",
+                        ext_int="external" if link.is_external else "internal",
+                        href=link.href,
+                        title=link.title,
+                    )
+                )
             )
 
         # The first links will always be visible