feat: dropdown for navigation bar

doc/changelog.d/723.added.md

@@ -0,0 +1 @@
+Dropdown for navigation bar

doc/source/user-guide/options.rst

@@ -344,7 +344,7 @@
 
            print("hello world")
 
 If a format is used in the "content" field that does not fall into the categories above, it will not
 be rendered correctly.
 
 To enable the "What's new" sections and sidebar in the changelog file, add the following dictionary
@@ -367,9 +367,9 @@
 The dictionary contains the following keys:
 
 - ``whatsnew_file_path``: The path to the YAML file containing what's new content local to the
   ``doc/source`` directory. If not provided, the what's new section will not be generated.
 - ``changelog_file_path``: The path to the changelog.rst file local to the ``doc/source``
   directory. If not provided, the what's new section will not be generated.
 - ``sidebar_pages``: List of names for the pages to include the what's new sidebar on. If not
   provided, the what's new sidebar is not displayed.
 - ``sidebar_no_of_headers``: Number of minor version sections to display in the what's new sidebar.
@@ -394,6 +394,52 @@
 
 .. note::
 
     If you are using both the "whatsnew" and "cheatsheet" options, the "cheatsheet" option will be
     displayed first in the left navigation pane, followed by the "What's new" section to maintain
-    sidebar consistency.
+    sidebar consistency.
+
+Navigation bar dropdown
+------------------------
+This theme supports dropdown navigation bars. The layout is declared using a YAML file contained at any level in the ``doc/source`` directory.
+The file path is relative to the ``doc/source`` directory,and must be specified in the ``html_theme_options`` dictionary.
+
+- ``navigation_yaml_file``: The path to the YAML file containing the navigation structure.
+
+.. code:: python
+
+    html_theme_options = {
+        ...,
+        "navigation_dropdown": {
+            "layout_file": "navbar.yml", # Relative path to the YAML file
+        },
+    }
+
+Each entry in the YAML file may include the following fields:
+
+- **file.** The relative path to the documentation file, based on the doc/source directory.
+
+- **title.** The text displayed for the link in the dropdown navigation menu.
+
+- **sections.** A list of nested navigation items. Each section can specify its own file, title, and an optional caption to provide a brief description.
+
+.. code:: yaml
+
+    - file: api/index
+      title: "API Reference"
+
+    - file: examples
+      title: "Examples"
+      sections:
+
+        - file: examples/sphinx-design.rst
+          title: "Sphinx Design Examples"
+          caption: Examples of using Sphinx design features
+
+        - file: examples/nbsphinx
+          title: "Nbsphinx Examples"
+          caption: Examples of using Nbsphinx for Jupyter Notebooks
+
+
+.. warning::
+
+    You must declare the complete layout of the dropdown navigation bar in the YAML file. Sphinx does not resolve it automatically.

pyproject.toml

@@ -35,6 +35,7 @@ dependencies = [
     "Jinja2>=3.1.2",
     "importlib-metadata>=4.0",
     "pdf2image>=1.17.0",
+    "PyYAML==6.0.2",
 ]
 
 [project.optional-dependencies]

src/ansys_sphinx_theme/__init__.py

@@ -35,6 +35,7 @@
 from ansys_sphinx_theme.cheatsheet import build_quarto_cheatsheet, cheatsheet_sidebar_pages
 from ansys_sphinx_theme.extension.linkcode import DOMAIN_KEYS, sphinx_linkcode_resolve
 from ansys_sphinx_theme.latex import generate_404
+from ansys_sphinx_theme.navbar_dropdown import load_navbar_configuration, update_template_context
 from ansys_sphinx_theme.search import (
     create_search_index,
     update_search_config,
@@ -494,6 +495,7 @@ def setup(app: Sphinx) -> Dict:
 
     # Add default HTML configuration
     setup_default_html_theme_options(app)
+    load_navbar_configuration(app)
 
     # Check for what's new options in the theme configuration
     whatsnew_file, changelog_file = get_whatsnew_options(app)
@@ -519,10 +521,12 @@ def setup(app: Sphinx) -> Dict:
     app.connect("html-page-context", update_footer_theme)
     app.connect("html-page-context", fix_edit_html_page_context)
     app.connect("html-page-context", update_search_sidebar_context)
+    app.connect("html-page-context", update_template_context)
 
     app.connect("build-finished", replace_html_tag)
     if use_ansys_search:
         app.connect("build-finished", create_search_index)
+
     return {
         "version": __version__,
         "parallel_read_safe": True,

src/ansys_sphinx_theme/navbar_dropdown.py

@@ -0,0 +1,155 @@
+# Copyright (C) 2021 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Navigation Dropdown for navigation bar."""
+
+import copy
+from functools import lru_cache
+import pathlib
+from typing import TypedDict
+
+import bs4
+from docutils import nodes
+import sphinx
+from sphinx.util import logging
+from sphinx.util.nodes import make_refnode
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+class NavEntry(TypedDict, total=False):
+    """Represents an entry in the navbar configuration."""
+
+    title: str
+    caption: str
+    file: str
+    link: str
+    sections: list["NavEntry"]
+
+
+def load_navbar_configuration(app: sphinx.application.Sphinx) -> None:
+    """Load the navbar configuration from a YAML file for the Sphinx app."""
+    navigation_theme_options = app.config.html_theme_options.get("navigation_dropdown", {})
+    if not navigation_theme_options or "layout_file" not in navigation_theme_options:
+        return
+
+    layout_file = navigation_theme_options["layout_file"]
+
+    yaml_path = pathlib.Path(app.srcdir) / layout_file
+
+    try:
+        yaml_content = yaml_path.read_text(encoding="utf-8")
+        app.config.navbar_contents = yaml.safe_load(yaml_content)
+
+    except FileNotFoundError:
+        raise FileNotFoundError(
+            f"Navbar layout file '{layout_file}' not found in: {yaml_path.parent.resolve()}"
+        )
+
+    except yaml.YAMLError as exc:
+        raise ValueError(f"Failed to parse YAML in '{yaml_path.name}': {exc}")
+
+
+def update_template_context(
+    app: sphinx, pagename: str, templatename: str, context: dict, doctree: nodes.document | None
+) -> None:
+    """Inject navbar rendering logic into the Sphinx HTML template context."""
+
+    @lru_cache(maxsize=None)
+    def render_navbar_links_html() -> bs4.BeautifulSoup:
+        """Render the navbar content as HTML using the navbar configuration."""
+        if not hasattr(app.config, "navbar_contents"):
+            raise ValueError("Navbar configuration not found. Please define a layout YAML file.")
+
+        nav_root = nodes.container(classes=["navbar-content"])
+        nav_root.append(build_navbar_nodes(app.config.navbar_contents))
+        rendered = app.builder.render_partial(nav_root)["fragment"]
+        return add_navbar_chevrons(bs4.BeautifulSoup(rendered, "html.parser"))
+
+    def build_navbar_nodes(entries: list[NavEntry], is_top_level: bool = True) -> nodes.bullet_list:
+        """Recursively construct docutils nodes for the navbar structure."""
+        classes = ["navbar-toplevel"] if is_top_level else ["navbar-sublevel"]
+        nav_list = nodes.bullet_list(bullet="-", classes=classes)
+
+        for entry in entries:
+            title = entry.get("title", "")
+            file = entry.get("file")
+            link = entry.get("link")
+
+            if file:
+                ref_node = make_refnode(
+                    app.builder,
+                    context["current_page_name"],
+                    file,
+                    None,
+                    nodes.inline(classes=["navbar-link-title"], text=title),
+                    title,
+                )
+            elif link:
+                ref_node = nodes.reference("", "", internal=False)
+                ref_node["refuri"] = link
+                ref_node["reftitle"] = title
+                ref_node.append(nodes.inline(classes=["navbar-link-title"], text=title))
+            else:
+                logger.warning(
+                    f"Invalid navbar entry: {entry}. Expected 'file' or 'link'. Skipping."
+                )
+                continue
+
+            if "caption" in entry:
+                ref_node.append(nodes.Text(entry["caption"]))
+
+            paragraph = nodes.paragraph()
+            paragraph.append(ref_node)
+
+            container = nodes.container(classes=["ref-container"])
+            container.append(paragraph)
+
+            list_item_classes = ["active-link"] if file == pagename else []
+            list_item = nodes.list_item(classes=list_item_classes)
+            list_item.append(container)
+
+            if "sections" in entry:
+                dropdown = nodes.container(classes=["navbar-dropdown"])
+                dropdown.append(build_navbar_nodes(entry["sections"], is_top_level=False))
+                list_item.append(dropdown)
+
+            nav_list.append(list_item)
+
+        return nav_list
+
+    context["render_navbar_links_html"] = render_navbar_links_html
+
+
+def add_navbar_chevrons(soup: bs4.BeautifulSoup) -> bs4.BeautifulSoup:
+    """Add chevron icons to navbar items that have dropdown menus."""
+    soup_copy = copy.copy(soup)
+
+    for li in soup_copy.find_all("li", recursive=True):
+        if li.find("div", class_="navbar-dropdown", recursive=False):
+            ref_container = li.find("div", class_="ref-container")
+            if ref_container:
+                chevron = soup_copy.new_tag("i", attrs={"class": "fa-solid fa-chevron-down"})
+                ref_container.append(chevron)
+
+    return soup_copy

src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/navbar-nav.html

@@ -0,0 +1,88 @@
+{% if theme_navigation_dropdown %}
+<nav class="navbar-nav">
+  <p class="sidebar-header-items__title"
+     role="heading"
+     aria-level="1"
+     aria-label="{{ _('Site Navigation') }}">
+    <!-- {{ _("Site Navigation") }} -->
+  </p>
+  {{ render_navbar_links_html() }}
+</nav>
+<style>
+  /* Top navbar styling */
+.navbar-toplevel p {
+  margin: 0;
+  padding-inline-start: 0;
+}
+div.navbar-dropdown {
+    display: none;
+    position: relative;
+    left: -100%;
+    margin-top: 2rem;
+}
+.navbar-sublevel p a.reference {
+  text-decoration: none;
+}
+.navbar-sublevel p a.reference:hover > span.navbar-link-title {
+  text-decoration: underline;
+  color: var(--pst-color-link-hover);
+}
+.navbar-toplevel li {
+  display: inline-flex;
+  justify-content: center;
+  align-items: center;
+  height: 100%;
+  padding: 0em 1em;
+
+}
+
+ul.navbar-toplevel li:hover > div.navbar-dropdown {
+  display: block;
+}
+
+.navbar-content ul.navbar-sublevel {
+  position: absolute;
+  gap: 1rem;
+  padding: 1em 1em;
+  display: flex;
+  flex-direction: column;
+  align-items: baseline;
+  background-color: white;
+  white-space: pre;
+  box-shadow: 0 5px 15px 0 rgb(0 0 0 / 10%);
+}
+
+div.navbar-content a {
+  display: flex;
+  flex-direction: column;
+  color: var(--ast-navbar-color);
+  align-items: baseline;
+  justify-content: center;
+  font-weight: var(--ast-font-weight-semibold);
+}
+.ref-container {
+  display: flex;
+  flex-direction: row;
+  gap: 0.5em;
+  font-family: var(--ast-body-family);
+  line-height: var(--ast-global-line-height);
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+}
+/* Highlight active nav bar link */
+li.active-link {
+  font-weight: bold;
+}
+/* Set the first .navbar-persistent--mobile element to have auto left margin */
+/* Disable underline for hovered links in the nav bar */
+.navbar-nav li a:hover {
+  text-decoration: none;
+}
+.navbar-header-items {
+  padding-left: 0;
+}
+</style>
+{% else %}
+{% include "pydata_sphinx_theme/components/navbar-nav.html" %}
+{% endif %}

src/ansys_sphinx_theme/theme/ansys_sphinx_theme/theme.conf

@@ -22,3 +22,4 @@ whatsnew =
 use_ansys_search = True
 search_extra_sources =
 search_filters =
+navigation_dropdown =