feat: add multi index searching and filtering (#674)

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

Author: 3 people

doc/changelog.d/674.added.md

@@ -0,0 +1 @@
+add multi index searching and filtering

doc/source/_static/search_filter.png

@@ -68,13 +68,23 @@
         "version_match": get_version_match(__version__),
     },
     "logo": "ansys",
-    "static_search": {
-        "threshold": 0.2,
-        "limit": 7,
-        "minMatchCharLength": 3,
+    "search_extra_sources": {
+        "PyDPF Core": "https:/dpf.docs.pyansys.com/version/stable/",
+        "Actions": "https://actions.docs.ansys.com/version/stable/",
+    },
+    "search_filters": {
+        "User Guide": [
+            "user-guide/",
+            "getting-started/",
+            "index/",
+        ],
+        "Release Notes": ["changelog"],
+        "Examples": ["examples/"],
+        "Contributing": ["contribute/"],
     },
 }
 
+
 html_js_files = ["https://cdn.plot.ly/plotly-3.0.1.min.js"]
 
 

doc/source/conf.py

@@ -147,23 +147,6 @@ Here is an example of how to add the ``static_search`` dictionary to the
         },
     }
 
-To customise the indexing of your documentation, you can use the ``index_patterns`` dictionary in the ``conf.py`` file.
-This dictionary contains the paths to the directories you want to index and the type of nodes to index.
-The type of nodes can be ``ALL_NODES``, ``TITLES`` or ``PARAGRAPHS``.
-The default value is ``TITLES + PARAGRAPHS``.
-
-Here is an example of how to add the ``index_patterns`` dictionary to the `conf.py`` file:
-
-.. code-block:: python
-
-    index_patterns = {
-        "api/": ALL_NODES,
-        "examples/": TITLES + PARAGRAPHS,
-    }
-
-The above example indexes all nodes in the ``api/`` directory and only titles and paragraphs in the ``examples/`` directory.
-
-
 .. note::
 
     All other options are available in the `Fuse.js documentation <https://fusejs.io/api/options.html>`_.
@@ -203,6 +186,63 @@ Here is an example of how to add the ``static_search`` dictionary to the
     Then, open the browser and go to ``http://localhost:8000``.
 
 
+Advanced search options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The Ansys Sphinx theme supports advanced search capabilities to enhance the user experience.
+
+These options can be configured through the ``html_theme_options`` dictionary in your ``conf.py`` file.
+
+Multi-index search
+^^^^^^^^^^^^^^^^^^
+
+To enable search across multiple documentation sources, use the ``search_extra_sources`` key.
+This key should be assigned a list of dictionaries, where each dictionary represents an external index.
+Each entry must contain a display name and the URL of the documentation to be included.
+
+**Example:**
+
+.. code-block:: python
+
+    html_theme_options = {
+        "search_extra_sources": [
+            {"name": "PyMAPDL", "url": "https://mapdl.docs.pyansys.com/version/stable/"},
+            {"name": "PyAnsys", "url": "https://docs.pyansys.com/version/stable/"},
+        ],
+    }
+
+Search filters
+^^^^^^^^^^^^^^
+
+To organize and group search results, you can define custom filters using the ``search_filters`` key.
+This key should be a dictionary where each key represents a filter label and the corresponding value is a list of directories or file paths that belong to that filter.
+
+**Example:**
+
+.. code-block:: python
+
+    html_theme_options = {
+        "search_filters": {
+            "User Guide": [
+                "user-guide/",
+                "getting-started/",
+                "index/",
+            ],
+            "Release Notes": ["changelog"],
+            "Examples": ["examples/"],
+            "Contributing": ["contribute/"],
+        },
+    }
+
+The filters appears as clickable options in the search interface, allowing users to refine their results by content type.
+
+The search filters are displayed as below:
+
+.. image:: ../_static/search_filter.png
+   :alt: Search filters
+
+
+
 Cheat sheets
 ------------
 

doc/source/user-guide/options.rst

@@ -36,9 +36,6 @@
 from ansys_sphinx_theme.extension.linkcode import DOMAIN_KEYS, sphinx_linkcode_resolve
 from ansys_sphinx_theme.latex import generate_404
 from ansys_sphinx_theme.search import (
-    ALL_NODES,
-    PARAGRAPHS,
-    TITLES,
     create_search_index,
     update_search_config,
 )
@@ -456,6 +453,35 @@ def add_sidebar_context(
     context["sidebars"] = sidebar
 
 
+def update_search_sidebar_context(
+    app: Sphinx, pagename: str, templatename: str, context: dict, doctree: nodes.document
+) -> None:
+    """Update the search sidebar context.
+
+    This function updates the search sidebar context with the search index
+    and the search options.
+
+    Parameters
+    ----------
+    app : sphinx.application.Sphinx
+        Application instance for rendering the documentation.
+    pagename : str
+        Name of the current page.
+    templatename : str
+        Name of the template being used.
+    context : dict
+        Context dictionary for the page.
+    doctree : docutils.nodes.document
+        Document tree for the page.
+    """
+    sidebar = context.get("sidebars", [])
+    if pagename == "search" and "search_sidebar.html" not in sidebar:
+        sidebar.append("search_sidebar.html")
+
+    # Update the sidebar context
+    context["sidebars"] = sidebar
+
+
 def append_og_site_name(app, pagename, templatename, context, doctree):
     # Make sure the context already has metatags
     context["metatags"] = context.get("metatags", "")
@@ -511,6 +537,8 @@ 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", append_og_site_name)
+    app.connect("html-page-context", update_search_sidebar_context)
+
     app.connect("build-finished", replace_html_tag)
     if use_ansys_search:
         app.connect("build-finished", create_search_index)
@@ -521,4 +549,8 @@ def setup(app: Sphinx) -> Dict:
     }
 
 
-__all__ = ["__version__", "generate_404", "get_version_match", "TITLES", "PARAGRAPHS", "ALL_NODES"]
+__all__ = [
+    "__version__",
+    "generate_404",
+    "get_version_match",
+]

src/ansys_sphinx_theme/__init__.py

@@ -35,9 +35,8 @@
 /* Result Title */
 .result-title {
   font-size: 1em;
-  font-weight: var(--ast-font-weight-bold);
   font-family: "Open Sans", sans-serif;
-  color: var(--ast-catagory-header-text);
+  color: var(--ast-color-link);
 }
 
 /* Result Text */
@@ -49,8 +48,8 @@
 
 /* Highlighted Text */
 html[data-theme="light"] .highlight {
-  color: var(--ast-highlight-color);
-  font-family: var(--ast-code-family);
+  color: var(--pst-color-text-base);
+  font-weight: var(--ast-font-weight-bold);
 }
 
 /* Search Input Styles */
@@ -166,4 +165,124 @@ html[data-theme="light"] .highlight {
   .bd-search .search-button__kbd-shortcut {
     display: none;
   }
+}
+
+
+/* ========== General Styles ========== */
+
+.result-item {
+  padding: 8px;
+  margin-bottom: 4px;
+  cursor: pointer;
+}
+
+.dropdown-menu.show {
+  display: block;
+}
+
+.dropdown-item {
+  padding: 10px;
+  cursor: pointer;
+}
+
+/* ========== Search Input ========== */
+
+#search-input {
+  width: 100%;
+  max-width: 600px; /* Adjust as needed */
+  padding: 10px;
+  margin-bottom: 10px;
+}
+
+/* ========== Checkbox Filter Items ========== */
+
+.checkbox-item {
+  display: flex;
+  align-items: center;
+  margin: 0.3125rem 0.625rem; // 5px 10px
+}
+
+
+
+/* ========== Chips (Selected Filter Tags) ========== */
+
+.chip {
+  display: inline-flex;
+  align-items: center;
+  background-color: var(--ast-hover-suggestion-text-background);
+  border-radius: 1rem; // 16px
+  padding: 0.3125rem 0.625rem; // 5px 10px
+  margin: 0.3125rem; // 5px
+}
+
+.chip .remove-btn {
+  margin-left: 0.5rem; // 8px
+  background: none;
+  border: none;
+  color:var(--ast-search-bar-enable-text);
+  cursor: pointer;
+  font-weight: bold;
+}
+
+.chip .remove-btn:hover {
+  color: var(--ast-search-bar-enable-background);
+}
+
+/* Dropdown items inside chips if needed */
+.chip .dropdown-item {
+  padding: 0.3125rem 0.625rem; // 5px 10px
+  cursor: pointer;
+}
+
+/* ========== Dropdown Panels (Sidebar) ========== */
+
+#objectid-dropdown,
+#library-dropdown {
+  position: relative;
+  top: 100%; /* Directly below parent */
+  left: 0.625rem; // 10px
+  background-color: transparent;
+  border: none;
+  display: block;
+}
+
+.search-page-sidebar.toggle-section {
+  display: flex;
+  align-items: center;
+  cursor: pointer;
+  padding: 0.3125rem 0.625rem; // 5px 10px
+  border-radius: 0.3125rem; // 5px
+  margin-top: 0.3125rem; // 5px
+}
+
+.search-page-sidebar.toggle-section.active {
+  background-color: var(--ast-hover-suggestion-text-background);
+  font-weight: bold;
+}
+
+.toggle-icon {
+  padding: 0.5rem; // 8px
+}
+
+.checkmark {
+  margin-right: 0.3125rem; // 5px
+  color: var(--ast-search-bar-enable-text);
+  font-weight: 400;
+}
+
+.result-limit-wrapper {
+  display: flex;
+  align-items: center;
+  margin: 0 0.625rem; // 0 10px
+  font-size: 0.875rem; /* 14px */
+  color: var(--ast-search-bar-enable-text);
+}
+
+select {
+  background-color: var(--ast-search-bar-enable-background);
+  color: var(--ast-search-bar-enable-text);
+  border: 0.03125rem solid var(--ast-search-bar-enable-border); /* 0.5px */
+  border-radius: 0.25rem; /* 4px */
+  padding: 0.5rem;
+  font-size: 0.875rem; /* 14px */
 }

src/ansys_sphinx_theme/assets/styles/ast-search.scss

@@ -24,10 +24,6 @@
 from sphinx.application import Sphinx
 
 from ansys_sphinx_theme.search.fuse_search import (
-    ALL_NODES,
-    LITERAL,
-    PARAGRAPHS,
-    TITLES,
     create_search_index,
 )
 
@@ -41,7 +37,7 @@ def update_search_config(app: Sphinx) -> None:
         Sphinx application.
     """
     theme_static_options = app.config.html_theme_options.get("static_search", {})
-    theme_static_options["keys"] = ["title", "text"]
+    theme_static_options["keys"] = ["title", "text", "objectID"]
     theme_static_options["threshold"] = theme_static_options.get("threshold", 0.2)
     theme_static_options["limit"] = theme_static_options.get("limit", 10)
     app.add_config_value("index_patterns", {}, "html")
@@ -51,8 +47,4 @@ def update_search_config(app: Sphinx) -> None:
 __all__ = [
     "create_search_index",
     "update_search_config",
-    "LITERAL",
-    "PARAGRAPHS",
-    "TITLES",
-    "ALL_NODES",
 ]