Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/builders/html/__init__.py

@@ -5,14 +5,15 @@ from __future__ import annotations
 import contextlib
 import html
 import os
+import os.path
 import posixpath
 import re
 import shutil
 import sys
 import warnings
-from os import path
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from types import NoneType
+from typing import TYPE_CHECKING
 from urllib.parse import quote
 
 import docutils.readers.doctree
@@ -20,10 +21,10 @@ from docutils import nodes
 from docutils.core import Publisher
 from docutils.frontend import OptionParser
 from docutils.io import DocTreeInput, StringOutput
-from docutils.utils import relative_path
 
 from sphinx import __display_version__, package_dir
 from sphinx import version_info as sphinx_version
+from sphinx._cli.util.colour import bold
 from sphinx.builders import Builder
 from sphinx.builders.html._assets import (
     _CascadingStyleSheet,
@@ -31,7 +32,7 @@ from sphinx.builders.html._assets import (
     _JavaScript,
 )
 from sphinx.builders.html._build_info import BuildInfo
-from sphinx.config import ENUM, Config
+from sphinx.config import ENUM
 from sphinx.deprecation import _deprecation_warning
 from sphinx.domains import Index, IndexEntry
 from sphinx.environment.adapters.asset import ImageAdapter
@@ -43,9 +44,9 @@ from sphinx.locale import _, __
 from sphinx.search import js_index
 from sphinx.theming import HTMLThemeFactory
 from sphinx.util import logging
+from sphinx.util._pathlib import _StrPath
 from sphinx.util._timestamps import _format_rfc3339_microseconds
 from sphinx.util._uri import is_url
-from sphinx.util.console import bold
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import new_document
 from sphinx.util.fileutil import copy_asset
@@ -55,9 +56,9 @@ from sphinx.util.matching import DOTFILES, Matcher, patmatch
 from sphinx.util.osutil import (
     SEP,
     _last_modified_time,
+    _relative_path,
     copyfile,
     ensuredir,
-    os_path,
     relative_uri,
 )
 from sphinx.writers.html import HTMLWriter
@@ -65,12 +66,13 @@ from sphinx.writers.html5 import HTML5Translator
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Set
-    from typing import TypeAlias
+    from typing import Any, TypeAlias
 
     from docutils.nodes import Node
     from docutils.readers import Reader
 
     from sphinx.application import Sphinx
+    from sphinx.config import Config
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import ExtensionMetadata
 
@@ -104,9 +106,7 @@ def convert_locale_to_language_tag(locale: str | None) -> str | None:
 
 
 class StandaloneHTMLBuilder(Builder):
-    """
-    Builds standalone HTML docs.
-    """
+    """Builds standalone HTML docs."""
 
     name = 'html'
     format = 'html'
@@ -138,6 +138,12 @@ class StandaloneHTMLBuilder(Builder):
     def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
         super().__init__(app, env)
 
+        # Static and asset directories
+        self._static_dir = Path(self.outdir / '_static')
+        self._sources_dir = Path(self.outdir / '_sources')
+        self._downloads_dir = Path(self.outdir / '_downloads')
+        self._images_dir = Path(self.outdir / '_images')
+
         # CSS files
         self._css_files: list[_CascadingStyleSheet] = []
 
@@ -187,23 +193,25 @@ class StandaloneHTMLBuilder(Builder):
     def create_build_info(self) -> BuildInfo:
         return BuildInfo(self.config, self.tags, frozenset({'html'}))
 
-    def _get_translations_js(self) -> str:
-        candidates = [
-            path.join(dir, self.config.language, 'LC_MESSAGES', 'sphinx.js')
-            for dir in self.config.locale_dirs
-        ] + [
-            path.join(
-                package_dir, 'locale', self.config.language, 'LC_MESSAGES', 'sphinx.js'
-            ),
-            path.join(
-                sys.prefix, 'share/sphinx/locale', self.config.language, 'sphinx.js'
-            ),
-        ]
+    def _get_translations_js(self) -> Path | None:
+        for dir_ in self.config.locale_dirs:
+            js_file = Path(dir_, self.config.language, 'LC_MESSAGES', 'sphinx.js')
+            if js_file.is_file():
+                return js_file
 
-        for jsfile in candidates:
-            if path.isfile(jsfile):
-                return jsfile
-        return ''
+        js_file = package_dir.joinpath(
+            'locale', self.config.language, 'LC_MESSAGES', 'sphinx.js'
+        )
+        if js_file.is_file():
+            return js_file
+
+        js_file = Path(
+            sys.prefix, 'share', 'sphinx', 'locale', self.config.language, 'sphinx.js'
+        )
+        if js_file.is_file():
+            return js_file
+
+        return None
 
     def _get_style_filenames(self) -> Iterator[str]:
         if isinstance(self.config.html_style, str):
@@ -268,7 +276,7 @@ class StandaloneHTMLBuilder(Builder):
         for filename in self._get_style_filenames():
             self.add_css_file(filename, priority=200)
 
-        for filename, attrs in self.app.registry.css_files:
+        for filename, attrs in self.env._registry.css_files:
             self.add_css_file(filename, **attrs)
 
         for filename, attrs in self.get_builder_config('css_files', 'html'):
@@ -295,7 +303,7 @@ class StandaloneHTMLBuilder(Builder):
         self.add_js_file('doctools.js', priority=200)
         self.add_js_file('sphinx_highlight.js', priority=200)
 
-        for filename, attrs in self.app.registry.js_files:
+        for filename, attrs in self.env._registry.js_files:
             self.add_js_file(filename or '', **attrs)
 
         for filename, attrs in self.get_builder_config('js_files', 'html'):
@@ -320,7 +328,7 @@ class StandaloneHTMLBuilder(Builder):
             return name
         else:
             # not given: choose a math_renderer from registered ones as possible
-            renderers = list(self.app.registry.html_inline_math_renderers)
+            renderers = list(self.env._registry.html_inline_math_renderers)
             if len(renderers) == 1:
                 # only default math_renderer (mathjax) is registered
                 return renderers[0]
@@ -333,9 +341,9 @@ class StandaloneHTMLBuilder(Builder):
                 return None
 
     def get_outdated_docs(self) -> Iterator[str]:
-        build_info_fname = self.outdir / '.buildinfo'
+        build_info_path = self.outdir / '.buildinfo'
         try:
-            build_info = BuildInfo.load(build_info_fname)
+            build_info = BuildInfo.load(build_info_path)
         except ValueError as exc:
             logger.warning(__('Failed to read build info file: %r'), exc)
         except OSError:
@@ -344,10 +352,10 @@ class StandaloneHTMLBuilder(Builder):
         else:
             if self.build_info != build_info:
                 # log the mismatch and backup the old build info
-                build_info_backup = build_info_fname.with_name('.buildinfo.bak')
+                build_info_backup = build_info_path.with_name('.buildinfo.bak')
                 try:
-                    shutil.move(build_info_fname, build_info_backup)
-                    self.build_info.dump(build_info_fname)
+                    shutil.move(build_info_path, build_info_backup)
+                    self.build_info.dump(build_info_path)
                 except OSError:
                     pass  # ignore errors
                 else:
@@ -355,7 +363,7 @@ class StandaloneHTMLBuilder(Builder):
                     msg = __(
                         'build_info mismatch, copying .buildinfo to .buildinfo.bak'
                     )
-                    logger.info(bold(__('building [html]: ')) + msg)
+                    logger.info(bold(__('building [html]: ')) + msg)  # NoQA: G003
 
                 yield from self.env.found_docs
                 return
@@ -363,14 +371,14 @@ class StandaloneHTMLBuilder(Builder):
         if self.templates:
             template_mtime = int(self.templates.newest_template_mtime() * 10**6)
             try:
-                old_mtime = _last_modified_time(build_info_fname)
+                old_mtime = _last_modified_time(build_info_path)
             except Exception:
                 pass
             else:
                 # Let users know they have a newer template
                 if template_mtime > old_mtime:
                     logger.info(
-                        bold('building [html]: ')
+                        bold('building [html]: ')  # NoQA: G003
                         + __(
                             'template %s has been changed since the previous build, '
                             'all docs will be rebuilt'
@@ -384,19 +392,19 @@ class StandaloneHTMLBuilder(Builder):
                 logger.debug('[build target] did not in env: %r', docname)
                 yield docname
                 continue
-            targetname = self.get_outfilename(docname)
+            target_name = self.get_output_path(docname)
             try:
-                targetmtime = _last_modified_time(targetname)
-            except Exception:
-                targetmtime = 0
+                target_mtime = _last_modified_time(target_name)
+            except OSError:
+                target_mtime = 0
             try:
                 doc_mtime = _last_modified_time(self.env.doc2path(docname))
                 srcmtime = max(doc_mtime, template_mtime)
-                if srcmtime > targetmtime:
+                if srcmtime > target_mtime:
                     logger.debug(
-                        '[build target] targetname %r(%s), template(%s), docname %r(%s)',
-                        targetname,
-                        _format_rfc3339_microseconds(targetmtime),
+                        '[build target] target_name %r(%s), template(%s), docname %r(%s)',
+                        target_name,
+                        _format_rfc3339_microseconds(target_mtime),
                         _format_rfc3339_microseconds(template_mtime),
                         docname,
                         _format_rfc3339_microseconds(doc_mtime),
@@ -488,24 +496,29 @@ class StandaloneHTMLBuilder(Builder):
         favicon = self.config.html_favicon or ''
 
         if not is_url(logo):
-            logo = path.basename(logo)
+            logo = os.path.basename(logo)
         if not is_url(favicon):
-            favicon = path.basename(favicon)
+            favicon = os.path.basename(favicon)
 
         self.relations = self.env.collect_relations()
 
         rellinks: list[tuple[str, str, str, str]] = []
         if self.use_index:
             rellinks.append(('genindex', _('General Index'), 'I', _('index')))
-        for indexname, indexcls, _content, _collapse in self.domain_indices:
+        for index_name, index_cls, _content, _collapse in self.domain_indices:
             # if it has a short name
-            if indexcls.shortname:
-                rellinks.append((indexname, indexcls.localname, '', indexcls.shortname))
+            if index_cls.shortname:
+                rellinks.append((
+                    index_name,
+                    index_cls.localname,
+                    '',
+                    index_cls.shortname,
+                ))
 
         # add assets registered after ``Builder.init()``.
-        for css_filename, attrs in self.app.registry.css_files:
+        for css_filename, attrs in self.env._registry.css_files:
             self.add_css_file(css_filename, **attrs)
-        for js_filename, attrs in self.app.registry.js_files:
+        for js_filename, attrs in self.env._registry.js_files:
             self.add_js_file(js_filename or '', **attrs)
 
         # back up _css_files and _js_files to allow adding CSS/JS files to a specific page.
@@ -555,6 +568,10 @@ class StandaloneHTMLBuilder(Builder):
             }
         self.globalcontext |= self.config.html_context
 
+        if self.copysource:
+            # Create _sources
+            ensuredir(self._sources_dir)
+
     def get_doc_context(self, docname: str, body: str, metatags: str) -> dict[str, Any]:
         """Collect items for the template context of a page."""
         # find out relations
@@ -656,6 +673,7 @@ class StandaloneHTMLBuilder(Builder):
         metatags = self.docwriter.clean_meta
 
         ctx = self.get_doc_context(docname, body, metatags)
+        ctx['has_maths_elements'] = self.docwriter._has_maths_elements
         self.handle_page(docname, ctx, event_arg=doctree)
 
     def write_doc_serialized(self, docname: str, doctree: nodes.document) -> None:
@@ -694,7 +712,7 @@ class StandaloneHTMLBuilder(Builder):
     def gen_additional_pages(self) -> None:
         # additional pages from conf.py
         for pagename, template in self.config.html_additional_pages.items():
-            logger.info(pagename + ' ', nonl=True)
+            logger.info('%s ', pagename, nonl=True)
             self.handle_page(pagename, {}, template)
 
         # the search page
@@ -705,8 +723,12 @@ class StandaloneHTMLBuilder(Builder):
         # the opensearch xml file
         if self.config.html_use_opensearch and self.search:
             logger.info('opensearch ', nonl=True)
-            fn = path.join(self.outdir, '_static', 'opensearch.xml')
-            self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn)
+            self.handle_page(
+                'opensearch',
+                {},
+                'opensearch.xml',
+                outfilename=self._static_dir / 'opensearch.xml',
+            )
 
     def write_genindex(self) -> None:
         # the total count of lines for each index letter, used to distribute
@@ -739,19 +761,19 @@ class StandaloneHTMLBuilder(Builder):
             self.handle_page('genindex', genindexcontext, 'genindex.html')
 
     def write_domain_indices(self) -> None:
-        for indexname, indexcls, content, collapse in self.domain_indices:
-            indexcontext = {
-                'indextitle': indexcls.localname,
+        for index_name, index_cls, content, collapse in self.domain_indices:
+            index_context = {
+                'indextitle': index_cls.localname,
                 'content': content,
                 'collapse_index': collapse,
             }
-            logger.info(indexname + ' ', nonl=True)
-            self.handle_page(indexname, indexcontext, 'domainindex.html')
+            logger.info('%s ', index_name, nonl=True)
+            self.handle_page(index_name, index_context, 'domainindex.html')
 
     def copy_image_files(self) -> None:
         if self.images:
-            stringify_func = ImageAdapter(self.app.env).get_original_image_uri
-            ensuredir(self.outdir / self.imagedir)
+            stringify_func = ImageAdapter(self.env).get_original_image_uri
+            ensuredir(self._images_dir)
             for src in status_iterator(
                 self.images,
                 __('copying images... '),
@@ -764,7 +786,7 @@ class StandaloneHTMLBuilder(Builder):
                 try:
                     copyfile(
                         self.srcdir / src,
-                        self.outdir / self.imagedir / dest,
+                        self._images_dir / dest,
                         force=True,
                     )
                 except Exception as err:
@@ -774,11 +796,11 @@ class StandaloneHTMLBuilder(Builder):
 
     def copy_download_files(self) -> None:
         def to_relpath(f: str) -> str:
-            return relative_path(self.srcdir, f)
+            return _relative_path(Path(f), self.srcdir).as_posix()
 
         # copy downloadable files
         if self.env.dlfiles:
-            ensuredir(self.outdir / '_downloads')
+            ensuredir(self._downloads_dir)
             for src in status_iterator(
                 self.env.dlfiles,
                 __('copying downloadable files... '),
@@ -788,7 +810,7 @@ class StandaloneHTMLBuilder(Builder):
                 stringify_func=to_relpath,
             ):
                 try:
-                    dest = self.outdir / '_downloads' / self.env.dlfiles[src][1]
+                    dest = self._downloads_dir / self.env.dlfiles[src][1]
                     ensuredir(dest.parent)
                     copyfile(self.srcdir / src, dest, force=True)
                 except OSError as err:
@@ -800,22 +822,21 @@ class StandaloneHTMLBuilder(Builder):
 
     def create_pygments_style_file(self) -> None:
         """Create a style file for pygments."""
-        pyg_path = path.join(self.outdir, '_static', 'pygments.css')
+        pyg_path = self._static_dir / 'pygments.css'
         with open(pyg_path, 'w', encoding='utf-8') as f:
             f.write(self.highlighter.get_stylesheet())
 
         if self.dark_highlighter:
-            dark_path = path.join(self.outdir, '_static', 'pygments_dark.css')
+            dark_path = self._static_dir / 'pygments_dark.css'
             with open(dark_path, 'w', encoding='utf-8') as f:
                 f.write(self.dark_highlighter.get_stylesheet())
 
     def copy_translation_js(self) -> None:
         """Copy a JavaScript file for translations."""
-        jsfile = self._get_translations_js()
-        if jsfile:
+        if js_file := self._get_translations_js():
             copyfile(
-                jsfile,
-                self.outdir / '_static' / 'translations.js',
+                js_file,
+                self._static_dir / 'translations.js',
                 force=True,
             )
 
@@ -827,14 +848,14 @@ class StandaloneHTMLBuilder(Builder):
                     js_path = Path(jsfile)
                     copyfile(
                         js_path,
-                        self.outdir / '_static' / js_path.name,
+                        self._static_dir / js_path.name,
                         force=True,
                     )
             else:
                 if js_stemmer_rawcode := self.indexer.get_js_stemmer_rawcode():
                     copyfile(
                         js_stemmer_rawcode,
-                        self.outdir / '_static' / '_stemmer.js',
+                        self._static_dir / '_stemmer.js',
                         force=True,
                     )
 
@@ -846,8 +867,8 @@ class StandaloneHTMLBuilder(Builder):
         if self.theme:
             for entry in reversed(self.theme.get_theme_dirs()):
                 copy_asset(
-                    Path(entry) / 'static',
-                    self.outdir / '_static',
+                    Path(entry, 'static'),
+                    self._static_dir,
                     excluded=DOTFILES,
                     context=context,
                     renderer=self.templates,
@@ -865,7 +886,7 @@ class StandaloneHTMLBuilder(Builder):
         for entry in self.config.html_static_path:
             copy_asset(
                 self.confdir / entry,
-                self.outdir / '_static',
+                self._static_dir,
                 excluded=excluded,
                 context=context,
                 renderer=self.templates,
@@ -878,7 +899,7 @@ class StandaloneHTMLBuilder(Builder):
             source_path = self.confdir / self.config.html_logo
             copyfile(
                 source_path,
-                self.outdir / '_static' / source_path.name,
+                self._static_dir / source_path.name,
                 force=True,
             )
 
@@ -887,14 +908,15 @@ class StandaloneHTMLBuilder(Builder):
             source_path = self.confdir / self.config.html_favicon
             copyfile(
                 source_path,
-                self.outdir / '_static' / source_path.name,
+                self._static_dir / source_path.name,
                 force=True,
             )
 
     def copy_static_files(self) -> None:
         try:
             with progress_message(__('copying static files'), nonl=False):
-                ensuredir(self.outdir / '_static')
+                # Ensure that the static directory exists
+                self._static_dir.mkdir(parents=True, exist_ok=True)
 
                 # prepare context for templates
                 context = self.globalcontext.copy()
@@ -969,12 +991,12 @@ class StandaloneHTMLBuilder(Builder):
         assert self.indexer is not None
         keep = set(self.env.all_docs).difference(docnames)
         try:
-            searchindexfn = path.join(self.outdir, self.searchindex_filename)
+            search_index_path = self.outdir / self.searchindex_filename
             if self.indexer_dumps_unicode:
-                with open(searchindexfn, encoding='utf-8') as ft:
+                with open(search_index_path, encoding='utf-8') as ft:
                     self.indexer.load(ft, self.indexer_format)
             else:
-                with open(searchindexfn, 'rb') as fb:
+                with open(search_index_path, 'rb') as fb:
                     self.indexer.load(fb, self.indexer_format)
         except (OSError, ValueError):
             if keep:
@@ -991,7 +1013,7 @@ class StandaloneHTMLBuilder(Builder):
     def index_page(self, pagename: str, doctree: nodes.document, title: str) -> None:
         # only index pages with title
         if self.indexer is not None and title:
-            filename = str(self.env.doc2path(pagename, base=False))
+            filename = self.env.doc2path(pagename, base=False)
             metadata = self.env.metadata.get(pagename, {})
             if 'no-search' in metadata or 'nosearch' in metadata:
                 self.indexer.feed(pagename, filename, '', new_document(''))
@@ -1003,15 +1025,18 @@ class StandaloneHTMLBuilder(Builder):
     ) -> str:
         if 'includehidden' not in kwargs:
             kwargs['includehidden'] = False
-        if kwargs.get('maxdepth') == '':
+        if kwargs.get('maxdepth') == '':  # NoQA: PLC1901
             kwargs.pop('maxdepth')
         toctree = global_toctree_for_doc(
             self.env, docname, self, collapse=collapse, **kwargs
         )
         return self.render_partial(toctree)['fragment']
 
-    def get_outfilename(self, pagename: str) -> str:
-        return path.join(self.outdir, os_path(pagename) + self.out_suffix)
+    def get_output_path(self, page_name: str, /) -> Path:
+        return Path(self.outdir, page_name + self.out_suffix)
+
+    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:
@@ -1030,7 +1055,7 @@ class StandaloneHTMLBuilder(Builder):
                 if matched and has_wildcard(pattern):
                     # warn if both patterns contain wildcards
                     if has_wildcard(matched):
-                        logger.warning(msg, pagename, 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
@@ -1049,7 +1074,8 @@ class StandaloneHTMLBuilder(Builder):
         pagename: str,
         addctx: dict[str, Any],
         templatename: str = 'page.html',
-        outfilename: str | None = None,
+        *,
+        outfilename: Path | None = None,
         event_arg: Any = None,
     ) -> None:
         ctx = self.globalcontext.copy()
@@ -1137,8 +1163,9 @@ class StandaloneHTMLBuilder(Builder):
                     return f'<script {" ".join(sorted(attrs))}>{body}</script>'
                 return f'<script>{body}</script>'
 
-            uri = pathto(os.fspath(js.filename), resource=True)
-            if 'MathJax.js?' in os.fspath(js.filename):
+            js_filename_str = os.fspath(js.filename)
+            uri = pathto(js_filename_str, resource=True)
+            if 'MathJax.js?' in js_filename_str:
                 # MathJax v2 reads a ``?config=...`` query parameter,
                 # special case this and just skip adding the checksum.
                 # https://docs.mathjax.org/en/v2.7-latest/configuration.html#considerations-for-using-combined-configuration-files
@@ -1159,21 +1186,21 @@ class StandaloneHTMLBuilder(Builder):
         self._js_files[:] = self._orig_js_files
 
         self.update_page_context(pagename, templatename, ctx, event_arg)
-        newtmpl = self.app.emit_firstresult(
+        if new_template := self.events.emit_firstresult(
             'html-page-context', pagename, templatename, ctx, event_arg
-        )
-        if newtmpl:
-            templatename = newtmpl
+        ):
+            templatename = new_template
 
         # sort JS/CSS before rendering HTML
         try:  # NoQA: SIM105
-            # Convert script_files to list to support non-list script_files (refs: #8889)
+            # Convert script_files to list to support non-list script_files
+            # See: https://github.com/sphinx-doc/sphinx/issues/8889
             ctx['script_files'] = sorted(
                 ctx['script_files'], key=lambda js: js.priority
             )
         except AttributeError:
             # Skip sorting if users modifies script_files directly (maybe via `html_context`).
-            # refs: #8885
+            # See: https://github.com/sphinx-doc/sphinx/issues/8885
             #
             # Note: priority sorting feature will not work in this case.
             pass
@@ -1200,22 +1227,23 @@ class StandaloneHTMLBuilder(Builder):
             )
             raise ThemeError(msg) from exc
 
-        if not outfilename:
-            outfilename = self.get_outfilename(pagename)
-        # outfilename's path is in general different from self.outdir
-        ensuredir(path.dirname(outfilename))
+        if outfilename:
+            output_path = Path(outfilename)
+        else:
+            output_path = self.get_output_path(pagename)
+        # The output path is in general different from self.outdir
+        ensuredir(output_path.parent)
         try:
-            with open(
-                outfilename, 'w', encoding=ctx['encoding'], errors='xmlcharrefreplace'
-            ) as f:
-                f.write(output)
+            output_path.write_text(
+                output, encoding=ctx['encoding'], errors='xmlcharrefreplace'
+            )
         except OSError as err:
-            logger.warning(__('error writing file %s: %s'), outfilename, err)
+            logger.warning(__('error writing file %s: %s'), output_path, err)
         if self.copysource and ctx.get('sourcename'):
             # copy the source file for the "show source" link
-            source_name = path.join(self.outdir, '_sources', os_path(ctx['sourcename']))
-            ensuredir(path.dirname(source_name))
-            copyfile(self.env.doc2path(pagename), source_name, force=True)
+            source_file_path = self._sources_dir / ctx['sourcename']
+            source_file_path.parent.mkdir(parents=True, exist_ok=True)
+            copyfile(self.env.doc2path(pagename), source_file_path, force=True)
 
     def update_page_context(
         self, pagename: str, templatename: str, ctx: dict[str, Any], event_arg: Any
@@ -1228,7 +1256,7 @@ class StandaloneHTMLBuilder(Builder):
 
     @progress_message(__('dumping object inventory'))
     def dump_inventory(self) -> None:
-        InventoryFile.dump(path.join(self.outdir, INVENTORY_FILENAME), self.env, self)
+        InventoryFile.dump(self.outdir / INVENTORY_FILENAME, self.env, self)
 
     def dump_search_index(self) -> None:
         if self.indexer is None:
@@ -1236,16 +1264,17 @@ class StandaloneHTMLBuilder(Builder):
 
         with progress_message(__('dumping search index in %s') % self.indexer.label()):
             self.indexer.prune(self.env.all_docs)
-            searchindexfn = path.join(self.outdir, self.searchindex_filename)
+            search_index_path = self.outdir / self.searchindex_filename
+            search_index_tmp = self.outdir / f'{self.searchindex_filename}.tmp'
             # first write to a temporary file, so that if dumping fails,
             # the existing index won't be overwritten
             if self.indexer_dumps_unicode:
-                with open(searchindexfn + '.tmp', 'w', encoding='utf-8') as ft:
+                with open(search_index_tmp, 'w', encoding='utf-8') as ft:
                     self.indexer.dump(ft, self.indexer_format)
             else:
-                with open(searchindexfn + '.tmp', 'wb') as fb:
+                with open(search_index_tmp, 'wb') as fb:
                     self.indexer.dump(fb, self.indexer_format)
-            os.replace(searchindexfn + '.tmp', searchindexfn)
+            Path(search_index_tmp).replace(search_index_path)
 
 
 def convert_html_css_files(app: Sphinx, config: Config) -> None:
@@ -1319,43 +1348,49 @@ def validate_math_renderer(app: Sphinx) -> None:
 
 def validate_html_extra_path(app: Sphinx, config: Config) -> None:
     """Check html_extra_paths setting."""
-    for entry in config.html_extra_path[:]:
-        extra_path = path.normpath(path.join(app.confdir, entry))
-        if not path.exists(extra_path):
+    html_extra_path = []
+    for entry in config.html_extra_path:
+        extra_path = (app.confdir / entry).resolve()
+        if extra_path.exists():
+            if (
+                app.outdir.drive == extra_path.drive
+                and extra_path.is_relative_to(app.outdir)
+            ):  # fmt: skip
+                logger.warning(
+                    __('html_extra_path entry %r is placed inside outdir'), entry
+                )
+            else:
+                html_extra_path.append(entry)
+        else:
             logger.warning(__('html_extra_path entry %r does not exist'), entry)
-            config.html_extra_path.remove(entry)
-        elif (
-            path.splitdrive(app.outdir)[0] == path.splitdrive(extra_path)[0]
-            and path.commonpath((app.outdir, extra_path)) == path.normpath(app.outdir)
-        ):  # fmt: skip
-            logger.warning(
-                __('html_extra_path entry %r is placed inside outdir'), entry
-            )
-            config.html_extra_path.remove(entry)
+    config.html_extra_path = html_extra_path
 
 
 def validate_html_static_path(app: Sphinx, config: Config) -> None:
     """Check html_static_paths setting."""
-    for entry in config.html_static_path[:]:
-        static_path = path.normpath(path.join(app.confdir, entry))
-        if not path.exists(static_path):
+    html_static_path = []
+    for entry in config.html_static_path:
+        static_path = (app.confdir / entry).resolve()
+        if static_path.exists():
+            if (
+                app.outdir.drive == static_path.drive
+                and static_path.is_relative_to(app.outdir)
+            ):  # fmt: skip
+                logger.warning(
+                    __('html_static_path entry %r is placed inside outdir'), entry
+                )
+            else:
+                html_static_path.append(entry)
+        else:
             logger.warning(__('html_static_path entry %r does not exist'), entry)
-            config.html_static_path.remove(entry)
-        elif (
-            path.splitdrive(app.outdir)[0] == path.splitdrive(static_path)[0]
-            and path.commonpath((app.outdir, static_path)) == path.normpath(app.outdir)
-        ):  # fmt: skip
-            logger.warning(
-                __('html_static_path entry %r is placed inside outdir'), entry
-            )
-            config.html_static_path.remove(entry)
+    config.html_static_path = html_static_path
 
 
 def validate_html_logo(app: Sphinx, config: Config) -> None:
     """Check html_logo setting."""
     if (
         config.html_logo
-        and not path.isfile(path.join(app.confdir, config.html_logo))
+        and not (app.confdir / config.html_logo).is_file()
         and not is_url(config.html_logo)
     ):
         logger.warning(__('logo file %r does not exist'), config.html_logo)
@@ -1366,7 +1401,7 @@ def validate_html_favicon(app: Sphinx, config: Config) -> None:
     """Check html_favicon setting."""
     if (
         config.html_favicon
-        and not path.isfile(path.join(app.confdir, config.html_favicon))
+        and not (app.confdir / config.html_favicon).is_file()
         and not is_url(config.html_favicon)
     ):
         logger.warning(__('favicon file %r does not exist'), config.html_favicon)
@@ -1406,56 +1441,78 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(StandaloneHTMLBuilder)
 
     # config values
-    app.add_config_value('html_theme', 'alabaster', 'html')
-    app.add_config_value('html_theme_path', [], 'html')
-    app.add_config_value('html_theme_options', {}, 'html')
+    app.add_config_value('html_theme', 'alabaster', 'html', types=frozenset({str}))
+    app.add_config_value('html_theme_path', [], 'html', types=frozenset({list, tuple}))
+    app.add_config_value('html_theme_options', {}, 'html', types=frozenset({dict}))
     app.add_config_value(
         'html_title',
         lambda c: _('%s %s documentation') % (c.project, c.release),
         'html',
-        str,
+        types=frozenset({str}),
+    )
+    app.add_config_value(
+        'html_short_title', lambda self: self.html_title, 'html', types=frozenset({str})
+    )
+    app.add_config_value(
+        'html_style', None, 'html', types=frozenset({list, str, tuple})
+    )
+    app.add_config_value('html_logo', None, 'html', types=frozenset({str}))
+    app.add_config_value('html_favicon', None, 'html', types=frozenset({str}))
+    app.add_config_value('html_css_files', [], 'html', types=frozenset({list, tuple}))
+    app.add_config_value('html_js_files', [], 'html', types=frozenset({list, tuple}))
+    app.add_config_value('html_static_path', [], 'html', types=frozenset({list, tuple}))
+    app.add_config_value('html_extra_path', [], 'html', types=frozenset({list, tuple}))
+    app.add_config_value('html_last_updated_fmt', None, 'html', types=frozenset({str}))
+    app.add_config_value(
+        'html_last_updated_use_utc', False, 'html', types=frozenset({bool})
+    )
+    app.add_config_value('html_sidebars', {}, 'html', types=frozenset({dict}))
+    app.add_config_value('html_additional_pages', {}, 'html', types=frozenset({dict}))
+    app.add_config_value(
+        'html_domain_indices',
+        True,
+        'html',
+        types=frozenset({frozenset, list, set, tuple}),
+    )
+    app.add_config_value('html_permalinks', True, 'html', types=frozenset({bool}))
+    app.add_config_value('html_permalinks_icon', '¶', 'html', types=frozenset({str}))
+    app.add_config_value('html_use_index', True, 'html', types=frozenset({bool}))
+    app.add_config_value('html_split_index', False, 'html', types=frozenset({bool}))
+    app.add_config_value('html_copy_source', True, 'html', types=frozenset({bool}))
+    app.add_config_value('html_show_sourcelink', True, 'html', types=frozenset({bool}))
+    app.add_config_value(
+        'html_sourcelink_suffix', '.txt', 'html', types=frozenset({str})
+    )
+    app.add_config_value('html_use_opensearch', '', 'html', types=frozenset({str}))
+    app.add_config_value('html_file_suffix', None, 'html', types=frozenset({str}))
+    app.add_config_value('html_link_suffix', None, 'html', types=frozenset({str}))
+    app.add_config_value('html_show_copyright', True, 'html', types=frozenset({bool}))
+    app.add_config_value(
+        'html_show_search_summary', True, 'html', types=frozenset({bool})
+    )
+    app.add_config_value('html_show_sphinx', True, 'html', types=frozenset({bool}))
+    app.add_config_value('html_context', {}, 'html', types=frozenset({dict}))
+    app.add_config_value(
+        'html_output_encoding', 'utf-8', 'html', types=frozenset({str})
+    )
+    app.add_config_value('html_compact_lists', True, 'html', types=frozenset({bool}))
+    app.add_config_value('html_secnumber_suffix', '. ', 'html', types=frozenset({str}))
+    app.add_config_value('html_search_language', None, 'html', types=frozenset({str}))
+    app.add_config_value('html_search_options', {}, 'html', types=frozenset({dict}))
+    app.add_config_value('html_search_scorer', '', '', types=frozenset({str}))
+    app.add_config_value(
+        'html_scaled_image_link', True, 'html', types=frozenset({bool})
     )
-    app.add_config_value('html_short_title', lambda self: self.html_title, 'html')
-    app.add_config_value('html_style', None, 'html', {list, str})
-    app.add_config_value('html_logo', None, 'html', str)
-    app.add_config_value('html_favicon', None, 'html', str)
-    app.add_config_value('html_css_files', [], 'html')
-    app.add_config_value('html_js_files', [], 'html')
-    app.add_config_value('html_static_path', [], 'html')
-    app.add_config_value('html_extra_path', [], 'html')
-    app.add_config_value('html_last_updated_fmt', None, 'html', str)
-    app.add_config_value('html_last_updated_use_utc', False, 'html', types={bool})
-    app.add_config_value('html_sidebars', {}, 'html')
-    app.add_config_value('html_additional_pages', {}, 'html')
-    app.add_config_value('html_domain_indices', True, 'html', types={set, list})
-    app.add_config_value('html_permalinks', True, 'html')
-    app.add_config_value('html_permalinks_icon', '¶', 'html')
-    app.add_config_value('html_use_index', True, 'html')
-    app.add_config_value('html_split_index', False, 'html')
-    app.add_config_value('html_copy_source', True, 'html')
-    app.add_config_value('html_show_sourcelink', True, 'html')
-    app.add_config_value('html_sourcelink_suffix', '.txt', 'html')
-    app.add_config_value('html_use_opensearch', '', 'html')
-    app.add_config_value('html_file_suffix', None, 'html', str)
-    app.add_config_value('html_link_suffix', None, 'html', str)
-    app.add_config_value('html_show_copyright', True, 'html')
-    app.add_config_value('html_show_search_summary', True, 'html')
-    app.add_config_value('html_show_sphinx', True, 'html')
-    app.add_config_value('html_context', {}, 'html')
-    app.add_config_value('html_output_encoding', 'utf-8', 'html')
-    app.add_config_value('html_compact_lists', True, 'html')
-    app.add_config_value('html_secnumber_suffix', '. ', 'html')
-    app.add_config_value('html_search_language', None, 'html', str)
-    app.add_config_value('html_search_options', {}, 'html')
-    app.add_config_value('html_search_scorer', '', '')
-    app.add_config_value('html_scaled_image_link', True, 'html')
-    app.add_config_value('html_baseurl', '', 'html')
-    # removal is indefinitely on hold (ref: https://github.com/sphinx-doc/sphinx/issues/10265)
+    app.add_config_value('html_baseurl', '', 'html', types=frozenset({str}))
+    # removal is indefinitely on hold
+    # See: https://github.com/sphinx-doc/sphinx/issues/10265
     app.add_config_value(
-        'html_codeblock_linenos_style', 'inline', 'html', ENUM('table', 'inline')
+        'html_codeblock_linenos_style', 'inline', 'html', types=ENUM('table', 'inline')
     )
-    app.add_config_value('html_math_renderer', None, 'env')
-    app.add_config_value('html4_writer', False, 'html')
+    app.add_config_value(
+        'html_math_renderer', None, 'env', types=frozenset({str, NoneType})
+    )
+    app.add_config_value('html4_writer', False, 'html', types=frozenset({bool}))
 
     # events
     app.add_event('html-collect-pages')
@@ -1476,9 +1533,6 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     # load default math renderer
     app.setup_extension('sphinx.ext.mathjax')
 
-    # load transforms for HTML builder
-    app.setup_extension('sphinx.builders.html.transforms')
-
     return {
         'version': 'builtin',
         'parallel_read_safe': True,