fix: add title breadcrumbs (#515)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Jorge Martínez <[email protected]>

Author: 3 people

doc/changelog.d/515.fixed.md

@@ -0,0 +1 @@
+fix: add title breadcrumbs

src/ansys_sphinx_theme/search/fuse_search.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-"""Module to fuse search."""
+"""Module for generating search indices."""
 
 import json
 import re
@@ -29,84 +29,124 @@
 
 
 class SearchIndex:
-    """Class to get search index."""
+    """Generate a search index for a Sphinx document."""
 
     def __init__(self, doc_name, app):
-        """Initialize the class.
+        """
+        Initialize the search index object.
 
         Parameters
         ----------
         doc_name : str
-            Document name.
+            Name of the document.
         app : Sphinx
-            Sphinx application.
-        version : str
-            Version of the document for prefixing the path.
+            Sphinx application instance.
         """
-        self._doc_name = doc_name
-        self.doc_path = f"{self._doc_name}.html"
-        self.doc_title = app.env.titles[self._doc_name].astext()
-        self._doc_tree = app.env.get_doctree(self._doc_name)
+        self.doc_name = doc_name
+        self.doc_path = f"{self.doc_name}.html"
+        self.env = app.env
+        self.doc_title = self.env.titles[self.doc_name].astext()
+        self.doc_tree = self.env.get_doctree(self.doc_name)
         self.sections = []
 
-    def iterate_through_docs(self):
-        """Iterate through the document."""
-        for node in self._doc_tree.traverse(nodes.section):
-            self.section_title = node[0].astext()
-            self.section_text = "\n".join(
+    def build_sections(self):
+        """Build sections from the document tree."""
+        for node in self.doc_tree.traverse(nodes.section):
+            section_title = node[0].astext()
+            section_text = "\n".join(
                 n.astext()
                 for node_type in [nodes.paragraph, nodes.literal_block]
                 for n in node.traverse(node_type)
             )
-            self.section_anchor_id = _title_to_anchor(self.section_title)
+            section_anchor_id = _title_to_anchor(section_title)
             self.sections.append(
                 {
-                    "section_title": self.section_title,
-                    "section_text": self.section_text,
-                    "section_anchor_id": self.section_anchor_id,
+                    "title": section_title,
+                    "text": section_text,
+                    "anchor_id": section_anchor_id,
                 }
             )
 
+    def generate_breadcrumbs(self, section_title: str) -> str:
+        """
+        Generate title breadcrumbs from the document structure.
+
+        Parameters
+        ----------
+        section_title : str
+            The section title to generate breadcrumbs for.
+
+        Returns
+        -------
+        str
+            Breadcrumb string.
+
+        Notes
+        -----
+        The last part of `doc_name` is ignored because it represents the file name,
+        which is not needed for the breadcrumb trail. The breadcrumb trail is generated
+        by iterating over the parts of `doc_name` and fetching the title from the environment.
+        """
+        docs_parts = self.doc_name.split("/")[:-1]
+
+        breadcrumb_parts = [
+            self.env.titles[part].astext() for part in docs_parts if part in self.env.titles
+        ]
+
+        # Create breadcrumb hierarchy
+        breadcrumbs = " > ".join(breadcrumb_parts)
+        ignore_doc_title = section_title == self.doc_title
+
+        # Construct final breadcrumb path
+        if ignore_doc_title:
+            return f"{breadcrumbs} > {section_title}" if breadcrumbs else section_title
+
+        return (
+            f"{breadcrumbs} > {self.doc_title} > {section_title}"
+            if breadcrumbs
+            else f"{self.doc_title} > {section_title}"
+        )
+
     @property
     def indices(self):
-        """Get search index."""
-        for sections in self.sections:
-            search_index = {
-                "objectID": self._doc_name,
-                "href": f"{self.doc_path}#{sections['section_anchor_id']}",
-                "title": self.doc_title,
-                "section": sections["section_title"],
-                "text": sections["section_text"],
+        """Generate indices for each section."""
+        for section in self.sections:
+            breadcrumbs = self.generate_breadcrumbs(section["title"])
+            yield {
+                "objectID": self.doc_name,
+                "href": f"{self.doc_path}#{section['anchor_id']}",
+                "title": breadcrumbs,
+                "section": section["title"],
+                "text": section["text"],
             }
-            yield search_index
 
 
 def _title_to_anchor(title: str) -> str:
-    """Convert title to anchor."""
+    """Convert a title to a URL-friendly anchor identifier."""
     return re.sub(r"[^\w\s-]", "", title.lower().strip().replace(" ", "-"))
 
 
 def create_search_index(app, exception):
-    """Create search index for the document in build finished.
+    """
+    Generate search index at the end of the Sphinx build process.
 
     Parameters
     ----------
     app : Sphinx
-        Sphinx application.
-    exception : Any
-        Exception.
+        Sphinx application instance.
+    exception : Exception
+        Exception raised during the build process, if any.
     """
     if exception:
         return
 
-    all_docs = app.env.found_docs
     search_index_list = []
 
-    for document in all_docs:
+    for document in app.env.found_docs:
         search_index = SearchIndex(document, app)
-        search_index.iterate_through_docs()
+        search_index.build_sections()
         search_index_list.extend(search_index.indices)
 
-    search_index = app.builder.outdir / "_static" / "search.json"
-    with search_index.open("w", encoding="utf-8") as index_file:
+    search_index_path = app.builder.outdir / "_static" / "search.json"
+    with search_index_path.open("w", encoding="utf-8") as index_file:
         json.dump(search_index_list, index_file, ensure_ascii=False, indent=4)