From 3f6a0cc9fbc9139f4e56b346f5ac8f438eaee6fd Mon Sep 17 00:00:00 2001
From: Mehdi Nassim KHODJA <khodjamehdinassim@gmail.com>
Date: Sat, 15 Mar 2025 12:39:41 +0100
Subject: [PATCH] feat: add project-scoped search bar to sidebar

Currently, the theme has 2 different search options:
- Project-scoped search (page search.html)
- OpenStack-wide search (on the top of the page, header.html)

This change adds a sidebar that allows us to perform project-scoped
search directly from the sidebar from any page.
It's disabled by default but can be enabled via configuration.
Global search placeholder text has been updated to "Global Search"
in both themes (openstackdocs and starlingxdocs) to avoid confusion.

Change-Id: I4783c1efebc067532f1392d1d5c2d841ad895f39
Signed-off-by: Mehdi Nassim KHODJA <khodjamehdinassim@gmail.com>
---
 doc/source/index.rst                                     | 9 +++++++++
 openstackdocstheme/theme/openstackdocs/header.html       | 2 +-
 openstackdocstheme/theme/openstackdocs/sidebartoc.html   | 6 ++++++
 openstackdocstheme/theme/openstackdocs/theme.conf        | 1 +
 openstackdocstheme/theme/starlingxdocs/header.html       | 2 +-
 .../notes/add-sidebar-search-0e62a9438dca8309.yaml       | 4 ++++
 6 files changed, 22 insertions(+), 2 deletions(-)
 create mode 100644 releasenotes/notes/add-sidebar-search-0e62a9438dca8309.yaml

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 5be1b2ab..601cbdca 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -170,6 +170,15 @@ navigation in the ``html_theme_options`` in the ``conf.py`` file::
         # ...
     }
 
+The search bar in the sidebar is disabled by default. To enable it, set
+the ``sidebar_search`` option to ``True`` for project-scoped search::
+
+    html_theme_options = {
+        # ...
+        "sidebar_search": True,
+        # ...
+    }
+
 If you are using this theme for documentation you want to release based on git
 tags on your repository, set the release dropdown menu option in the
 ``html_theme_options`` in the ``conf.py`` file. By default it is set to
diff --git a/openstackdocstheme/theme/openstackdocs/header.html b/openstackdocstheme/theme/openstackdocs/header.html
index b002cae3..248639dc 100644
--- a/openstackdocstheme/theme/openstackdocs/header.html
+++ b/openstackdocstheme/theme/openstackdocs/header.html
@@ -17,7 +17,7 @@
         <span class="navbar-toggler-icon"></span>
         <span class="sr-only">Toggle navigation</span>
       </button>
-      <div class="search-icon show"><i class="fa fa-search"></i> Search</div>
+      <div class="search-icon show"><i class="fa fa-search"></i> Global Search</div>
       <div class="collapse navbar-collapse" id="navbar-main-1">
 {% include 'os_search.html' %}
       <ul class="nav navbar-nav navbar-main ms-auto mb-2 mb-lg-0 justify-content-end show" role="navigation">
diff --git a/openstackdocstheme/theme/openstackdocs/sidebartoc.html b/openstackdocstheme/theme/openstackdocs/sidebartoc.html
index aa985af6..9aef14ca 100644
--- a/openstackdocstheme/theme/openstackdocs/sidebartoc.html
+++ b/openstackdocstheme/theme/openstackdocs/sidebartoc.html
@@ -12,6 +12,12 @@
   {%- if theme_display_global_toc_section %}
     <div class="docs-sidebar-section" id="table-of-contents">
       <a href="{{ pathto(master_doc) }}" class="docs-sidebar-section-title"><h4>{{project}} {{version}}</h4></a>
+      {%- if theme_sidebar_search|tobool %}
+      <form action="{{ pathto('search') }}" method="get" class="input-group input-group-sm ps-3 pe-2 pb-3">
+        <input class="form-control" type="text" name="q" value="" placeholder="{% trans %}Search in {{project}}{% endtrans %}" aria-label="{% trans %}Search{% endtrans %}">
+        <button class="btn btn-outline-secondary" type="submit"><i class="fa fa-search"></i></button>
+      </form>
+      {%- endif %}
       {%- if theme_sidebar_mode == 'toc' %}
       {{ toc }}
       {%- elif theme_sidebar_mode == 'toctree' %}
diff --git a/openstackdocstheme/theme/openstackdocs/theme.conf b/openstackdocstheme/theme/openstackdocs/theme.conf
index 8efb9157..5bb77abc 100644
--- a/openstackdocstheme/theme/openstackdocs/theme.conf
+++ b/openstackdocstheme/theme/openstackdocs/theme.conf
@@ -13,3 +13,4 @@ root_title = OpenStack Docs
 sidebar_dropdown = os_docs
 show_other_versions = False
 earliest_published_series = mitaka
+sidebar_search = False
diff --git a/openstackdocstheme/theme/starlingxdocs/header.html b/openstackdocstheme/theme/starlingxdocs/header.html
index 2bf22651..8b4f5d9f 100644
--- a/openstackdocstheme/theme/starlingxdocs/header.html
+++ b/openstackdocstheme/theme/starlingxdocs/header.html
@@ -15,7 +15,7 @@
       <span class="navbar-toggler-icon"></span>
       <span class="sr-only">Toggle navigation</span>
     </button>
-    <div class="search-icon show"><i class="fa fa-search"></i> Search</div>
+    <div class="search-icon show"><i class="fa fa-search"></i> Global Search</div>
     <div class="collapse navbar-collapse" id="navbar-main-1">
       {% include 'stx_search.html' %}
       <ul class="nav navbar-nav navbar-main ms-auto mb-lg-0 justify-content-end show" role="navigation">
diff --git a/releasenotes/notes/add-sidebar-search-0e62a9438dca8309.yaml b/releasenotes/notes/add-sidebar-search-0e62a9438dca8309.yaml
new file mode 100644
index 00000000..93e31b0b
--- /dev/null
+++ b/releasenotes/notes/add-sidebar-search-0e62a9438dca8309.yaml
@@ -0,0 +1,4 @@
+---
+features:
+  - Add an optional project-scoped search bar to the sidebar. Updated OpenStack/StarlingX
+    wide search placeholder to "Global Search" for clarity.