openstack/openstackdocstheme
Code Issues Proposed changes

feat: add project-scoped search bar to sidebar

Browse Source 
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>
This commit is contained in:
Mehdi Nassim KHODJA 2025-03-15 12:39:41 +01:00 committed by Takashi Kajinami
parent 1d5cb6f4a1
commit 3f6a0cc9fb
6 changed files with 22 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/source/index.rst
View File

@ -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

2
openstackdocstheme/theme/openstackdocs/header.html
View File

@ -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">

6
openstackdocstheme/theme/openstackdocs/sidebartoc.html
View File

@ -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' %}

1
openstackdocstheme/theme/openstackdocs/theme.conf
View File

@ -13,3 +13,4 @@ root_title = OpenStack Docs
sidebar_dropdown = os_docs
show_other_versions = False
earliest_published_series = mitaka
sidebar_search = False

2
openstackdocstheme/theme/starlingxdocs/header.html
View File

@ -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">

4
releasenotes/notes/add-sidebar-search-0e62a9438dca8309.yaml Normal file
View File

@ -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.