From eaebbec4d165efcb5048fc06431e3bf796c9d224 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Mon, 1 Sep 2025 20:10:06 +0200
Subject: [PATCH] Refactor ``add_sidebars()`` into ``_get_sidebars()`` (#13863)

---
 sphinx/builders/html/__init__.py       | 23 +++++++++++++----------
 tests/test_builders/test_build_html.py | 18 +++++++-----------
 2 files changed, 20 insertions(+), 21 deletions(-)

diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
index 8cf0340100..6146201fa9 100644
--- a/sphinx/builders/html/__init__.py
+++ b/sphinx/builders/html/__init__.py
@@ -1040,31 +1040,30 @@ class StandaloneHTMLBuilder(Builder):
     def get_outfilename(self, pagename: str) -> _StrPath:
         return _StrPath(self.get_output_path(pagename))
 
-    def add_sidebars(self, pagename: str, ctx: dict[str, Any]) -> None:
-        def has_wildcard(pattern: str) -> bool:
-            return any(char in pattern for char in '*?[')
-
+    def _get_sidebars(self, pagename: str, /) -> tuple[str, ...]:
         matched = None
 
         # default sidebars settings for selected theme
-        sidebars = list(self.theme.sidebar_templates)
+        sidebars = self.theme.sidebar_templates
 
         # user sidebar settings
         html_sidebars = self.get_builder_config('sidebars', 'html')
         msg = __('page %s matches two patterns in html_sidebars: %r and %r')
         for pattern, pat_sidebars in html_sidebars.items():
             if patmatch(pagename, pattern):
-                if matched and has_wildcard(pattern):
+                if matched and _has_wildcard(pattern):
                     # warn if both patterns contain wildcards
-                    if has_wildcard(matched):
+                    if _has_wildcard(matched):
                         logger.warning(msg, pagename, matched, pattern)
                     # else the already matched pattern is more specific
                     # than the present one, because it contains no wildcard
                     continue
                 matched = pattern
-                sidebars = pat_sidebars
+                sidebars = tuple(pat_sidebars)
+        return sidebars
 
-        ctx['sidebars'] = list(sidebars)
+    def add_sidebars(self, pagename: str, ctx: dict[str, Any]) -> None:
+        ctx['sidebars'] = list(self._get_sidebars(pagename))
 
     # --------- these are overwritten by the serialization builder
 
@@ -1123,7 +1122,7 @@ class StandaloneHTMLBuilder(Builder):
         ctx['hasdoc'] = hasdoc
 
         ctx['toctree'] = lambda **kwargs: self._get_local_toctree(pagename, **kwargs)
-        self.add_sidebars(pagename, ctx)
+        ctx['sidebars'] = list(self._get_sidebars(pagename))
         ctx.update(addctx)
 
         # 'blah.html' should have content_root = './' not ''.
@@ -1292,6 +1291,10 @@ class StandaloneHTMLBuilder(Builder):
             Path(search_index_tmp).replace(search_index_path)
 
 
+def _has_wildcard(pattern: str, /) -> bool:
+    return any(char in pattern for char in '*?[')
+
+
 def convert_html_css_files(app: Sphinx, config: Config) -> None:
     """Convert string styled html_css_files to tuple styled one."""
     html_css_files: list[tuple[str, dict[str, str]]] = []
diff --git a/tests/test_builders/test_build_html.py b/tests/test_builders/test_build_html.py
index 3ba9c929cc..a0db51415a 100644
--- a/tests/test_builders/test_build_html.py
+++ b/tests/test_builders/test_build_html.py
@@ -30,8 +30,6 @@ from tests.test_builders.xpath_data import FIGURE_CAPTION
 from tests.test_builders.xpath_util import check_xpath
 
 if TYPE_CHECKING:
-    from typing import Any
-
     from sphinx.testing.util import SphinxTestApp
 
 
@@ -416,8 +414,6 @@ def test_html_style(app: SphinxTestApp) -> None:
     },
 )
 def test_html_sidebar(app: SphinxTestApp) -> None:
-    ctx: dict[str, Any] = {}
-
     # default for alabaster
     app.build(force_all=True)
     result = (app.outdir / 'index.html').read_text(encoding='utf8')
@@ -433,12 +429,12 @@ def test_html_sidebar(app: SphinxTestApp) -> None:
     assert '<h3>This Page</h3>' in result
 
     assert isinstance(app.builder, StandaloneHTMLBuilder)  # type-checking
-    app.builder.add_sidebars('index', ctx)
-    assert ctx['sidebars'] == [
+    sidebars = app.builder._get_sidebars('index')
+    assert sidebars == (
         'localtoc.html',
         'searchfield.html',
         'sourcelink.html',
-    ]
+    )
 
     # only sourcelink.html
     app.config.html_sidebars = {'**': ['sourcelink.html']}
@@ -456,8 +452,8 @@ def test_html_sidebar(app: SphinxTestApp) -> None:
     assert '<h3>This Page</h3>' in result
 
     assert isinstance(app.builder, StandaloneHTMLBuilder)  # type-checking
-    app.builder.add_sidebars('index', ctx)
-    assert ctx['sidebars'] == ['sourcelink.html']
+    sidebars = app.builder._get_sidebars('index')
+    assert sidebars == ('sourcelink.html',)
 
     # no sidebars
     app.config.html_sidebars = {'**': []}
@@ -477,8 +473,8 @@ def test_html_sidebar(app: SphinxTestApp) -> None:
     assert '<h3>This Page</h3>' not in result
 
     assert isinstance(app.builder, StandaloneHTMLBuilder)  # type-checking
-    app.builder.add_sidebars('index', ctx)
-    assert ctx['sidebars'] == []
+    sidebars = app.builder._get_sidebars('index')
+    assert sidebars == ()
 
 
 @pytest.mark.parametrize(