Add static types for the HTML context dict

Author: AA-Turner

sphinx/builders/html/__init__.py

@@ -70,7 +70,7 @@
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
-    from sphinx.builders.html._ctx import _GlobalContextHTML, _PageContext
+    from sphinx.builders.html._ctx import _GlobalContextHTML, _PageContextHTML
     from sphinx.config import Config
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import ExtensionMetadata
@@ -1043,7 +1043,7 @@ def get_output_path(self, page_name: str, /) -> Path:
     def get_outfilename(self, pagename: str) -> _StrPath:
         return _StrPath(self.get_output_path(pagename))
 
-    def add_sidebars(self, pagename: str, ctx: _PageContext) -> None:
+    def add_sidebars(self, pagename: str, ctx: _PageContextHTML) -> None:
         def has_wildcard(pattern: str) -> bool:
             return any(char in pattern for char in '*?[')
 
@@ -1083,7 +1083,7 @@ def handle_page(
         outfilename: Path | None = None,
         event_arg: Any = None,
     ) -> None:
-        ctx: _PageContext = self.globalcontext.copy()  # type: ignore[assignment]
+        ctx: _PageContextHTML = self.globalcontext.copy()  # type: ignore[assignment]
         # current_page_name is backwards compatibility
         ctx['pagename'] = ctx['current_page_name'] = pagename
         ctx['encoding'] = self.config.html_output_encoding
@@ -1264,7 +1264,7 @@ def js_tag(js: _JavaScript | str) -> str:
             copyfile(self.env.doc2path(pagename), source_file_path, force=True)
 
     def update_page_context(
-        self, pagename: str, templatename: str, ctx: _PageContext, event_arg: Any
+        self, pagename: str, templatename: str, ctx: _PageContextHTML, event_arg: Any
     ) -> None:
         pass
 

sphinx/builders/html/_ctx.py

@@ -55,7 +55,7 @@ def __call__(
     class _ToctreeCallable(Protocol):
         def __call__(self, **kwargs: Any) -> str: ...
 
-    class _PageContext(_GlobalContextHTML):
+    class _PageContextHTML(_GlobalContextHTML):
         # get_doc_context()
         prev: Sequence[_NavigationRelation]
         next: Sequence[_NavigationRelation]
@@ -84,4 +84,6 @@ class _PageContext(_GlobalContextHTML):
         sidebars: Sequence[str] | None
 
 else:
+    _NavigationRelation = dict
     _GlobalContextHTML = dict
+    _PageContextHTML = dict

tests/test_builders/test_build_html.py

@@ -30,7 +30,7 @@
 from tests.test_builders.xpath_util import check_xpath
 
 if TYPE_CHECKING:
-    from sphinx.builders.html._ctx import _PageContext
+    from sphinx.builders.html._ctx import _PageContextHTML
     from sphinx.testing.util import SphinxTestApp
 
 
@@ -415,7 +415,7 @@ def test_html_style(app: SphinxTestApp) -> None:
     },
 )
 def test_html_sidebar(app: SphinxTestApp) -> None:
-    ctx: _PageContext = {}  # type: ignore[typeddict-item]
+    ctx: _PageContextHTML = {}  # type: ignore[typeddict-item]
 
     # default for alabaster
     app.build(force_all=True)