feat: dropdown for navigation bar

.github/workflows/ci_cd.yml

@@ -147,6 +147,8 @@ jobs:
           - should-release: false
             os: macos-latest
     steps:
+      - name: "Install Git and clone project"
+        uses: actions/checkout@v4
       - name: "Build wheelhouse and perform smoke test"
         uses: ansys/actions/build-wheelhouse@8d3e4946f36c2a7d447b92e34b1022a5c9dc77a7 # v10.0.12
         with:

doc/changelog.d/723.added.md

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

doc/source/conf.py

@@ -82,6 +82,9 @@
         "Examples": ["examples/"],
         "Contributing": ["contribute/"],
     },
+    "navigation_dropdown": {
+        "layout_file": "navbar.yml",
+    },
 }
 
 

doc/source/navbar.yml

@@ -0,0 +1,26 @@
+- file: getting-started
+  title: "Get Started"
+- file: user-guide
+  title: "Use Cases"
+- file: api/index
+  title: "API Reference"
+- file: examples
+  title: "Examples"
+  sections:
+    - file: examples/sphinx-design
+      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
+- file: changelog
+  title: "New Features"
+- file: contribute
+  title: "Contribute"
+  sections:
+    - file: contribute/developer
+      title: developer contributions
+      caption: Contribute as a developer
+    - file: contribute/user
+      title: user contributions
+      caption: Contribute as a user

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,51 @@
 
 .. 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. This file must be specified in the ``html_theme_options`` so Sphinx can apply the desired navigation structure:
+
+- ``navigation_yaml_file``: The path to the YAML file containing the navigation structure.
+
+.. code:: python
+
+    html_theme_options = {
+            ...,
+            "navigation_dropdown": {
+                 "layout_file": "navbar.yml",
+             },
+    }
+
+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)
@@ -520,10 +522,12 @@ def setup(app: Sphinx) -> Dict:
     app.connect("html-page-context", fix_edit_html_page_context)
     app.connect("html-page-context", append_og_site_name)
     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,135 @@
+# 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 Dict, List, Union
+
+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__)
+
+
+def load_navbar_configuration(app: sphinx.application.Sphinx) -> None:
+    """Load the navbar configuration from a YAML file for the Sphinx app."""
+    if not (
+        "navigation_dropdown" in app.config.html_theme_options
+        and "layout_file" in app.config.html_theme_options["navigation_dropdown"]
+    ):
+        return
+
+    layout_file = app.config.html_theme_options["navigation_dropdown"].get("layout_file", None)
+    try:
+        with pathlib.Path.open(app.srcdir / layout_file, encoding="utf-8") as config_file:
+            app.config.navbar_contents = yaml.safe_load(config_file)
+    except FileNotFoundError:
+        raise FileNotFoundError(f"Could not find {layout_file}.")
+    except yaml.YAMLError as exc:
+        raise ValueError(f"Error parsing '{layout_file}': {exc}")
+
+
+NavEntry = Dict[str, Union[str, List["NavEntry"]]]
+"""Type alias for a navigation entry in the navbar configuration.
+
+Each entry can have a 'file' or 'link' key, and optionally 'title',
+'caption', and 'sections' keys. The 'sections' key contains a list of
+sub-entries, allowing for nested navigation structures.
+"""
+
+
+def update_template_context(app, pagename, templatename, context, doctree):
+    """Inject custom variables and utilities into the Sphinx template context."""
+
+    @lru_cache(maxsize=None)
+    def render_navbar_links_html() -> bs4.BeautifulSoup:
+        """Render external header links as HTML for the navbar."""
+        if not hasattr(app.config, "navbar_contents"):
+            raise ValueError("Navbar configuration is missing. Please specify a navbar YAML file.")
+        node = nodes.container(classes=["navbar-content"])
+        node.append(build_navbar_nodes(app.config.navbar_contents))
+        header_soup = bs4.BeautifulSoup(app.builder.render_partial(node)["fragment"], "html.parser")
+        return add_navbar_chevrons(header_soup)
+
+    def build_navbar_nodes(obj: List[NavEntry], is_top_level: bool = True) -> nodes.Node:
+        """Recursively build navbar nodes from configuration entries."""
+        bullet_list = nodes.bullet_list(
+            bullet="-",
+            classes=["navbar-toplevel" if is_top_level else "navbar-sublevel"],
+        )
+        for item in obj:
+            if "file" in item:
+                ref_node = make_refnode(
+                    app.builder,
+                    context["current_page_name"],
+                    item["file"],
+                    None,
+                    nodes.inline(classes=["navbar-link-title"], text=item.get("title")),
+                    item.get("title"),
+                )
+            elif "link" in item:
+                ref_node = nodes.reference("", "", internal=False)
+                ref_node["refuri"] = item.get("link")
+                ref_node["reftitle"] = item.get("title")
+                ref_node.append(nodes.inline(classes=["navbar-link-title"], text=item.get("title")))
+            else:
+                logger.warning(
+                    f"Navbar entry '{item}' is missing 'file' or 'link' key. Skipping this entry."
+                )
+                continue
+            if "caption" in item:
+                caption = nodes.Text(item.get("caption"))
+                ref_node.append(caption)
+            paragraph = nodes.paragraph()
+            paragraph.append(ref_node)
+            container = nodes.container(classes=["ref-container"])
+            container.append(paragraph)
+            list_item = nodes.list_item(
+                classes=["active-link"] if item.get("file") == pagename else []
+            )
+            list_item.append(container)
+            if "sections" in item:
+                wrapper = nodes.container(classes=["navbar-dropdown"])
+                wrapper.append(build_navbar_nodes(item["sections"], is_top_level=False))
+                list_item.append(wrapper)
+            bullet_list.append(list_item)
+        return bullet_list
+
+    context["render_navbar_links_html"] = render_navbar_links_html
+
+
+def add_navbar_chevrons(input_soup: bs4.BeautifulSoup) -> bs4.BeautifulSoup:
+    """Add dropdown chevron icons to navbar items with submenus."""
+    soup = copy.copy(input_soup)
+    for li in soup.find_all("li", recursive=True):
+        divs = li.find_all("div", {"class": "navbar-dropdown"}, recursive=False)
+        if divs:
+            ref = li.find("div", {"class": "ref-container"})
+            ref.append(soup.new_tag("i", attrs={"class": "fa-solid fa-chevron-down"}))
+    return soup

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 =