Merge branch 'master' into feat/line-matcher

CHANGES.rst

@@ -147,6 +147,9 @@ Bugs fixed
 * #12040: HTML Search: Ensure that document titles that are partially-matched by
   the user search query are included in search results.
   Patch by James Addison.
+* #11970: singlehtml builder: make target URIs to be same-document references in
+  the sense of :rfc:`RFC 3986, §4.4 <3986#section-4.4>`, e.g., ``index.html#foo``
+  becomes ``#foo``. Patch by eanorige.
 
 Testing
 -------

doc/conf.py

@@ -108,7 +108,7 @@
 linkcheck_timeout = 5
 linkcheck_ignore = [
     r'^contents\.html$',  # extra generated page
-    '^\.\./contents\.html$',
+    r'^\.\./contents\.html$',
     re.escape('https://gitlab.com/projects/new'),  # requires sign-in
     re.escape('https://web.libera.chat/?channel=#sphinx-doc'),
 ]

doc/development/theming.rst

@@ -35,6 +35,9 @@ theme name), containing the following:
 * A ``static/`` directory containing any static files that will be copied to the
   output static directory on build.  These can be images, styles, script files.
 
+Theme configuration (``theme.conf``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
 Python :mod:`configparser` module) and has the following structure:
 

pyproject.toml

@@ -286,7 +286,7 @@ module = [
 disallow_any_generics = false
 
 [tool.pytest.ini_options]
-minversion = 6.0
+minversion = "6.0"
 addopts = [
     "-ra",
     "--import-mode=prepend",

sphinx/builders/__init__.py

@@ -314,8 +314,7 @@ def build(
 
         doccount = len(updated_docnames)
         logger.info(bold(__('looking for now-outdated files... ')), nonl=True)
-        for docname in self.env.check_dependents(self.app, updated_docnames):
-            updated_docnames.add(docname)
+        updated_docnames.update(self.env.check_dependents(self.app, updated_docnames))
         outdated = len(updated_docnames) - doccount
         if outdated:
             logger.info(__('%d found'), outdated)

sphinx/builders/gettext.py

@@ -27,7 +27,7 @@
 
 if TYPE_CHECKING:
     import os
-    from collections.abc import Generator, Iterable
+    from collections.abc import Iterable, Iterator
 
     from docutils.nodes import Element
 
@@ -69,7 +69,7 @@ def add(self, msg: str, origin: Element | MsgOrigin) -> None:
             line = -1
         self.metadata[msg].append((origin.source, line, origin.uid))  # type: ignore[arg-type]
 
-    def __iter__(self) -> Generator[Message, None, None]:
+    def __iter__(self) -> Iterator[Message]:
         for message in self.messages:
             positions = sorted({(source, line) for source, line, uuid
                                in self.metadata[message]})

sphinx/builders/html/__init__.py

@@ -265,8 +265,7 @@ def _get_style_filenames(self) -> Iterator[str]:
         elif self.config.html_style is not None:
             yield from self.config.html_style
         elif self.theme:
-            stylesheet = self.theme.get_config('theme', 'stylesheet')
-            yield from map(str.strip, stylesheet.split(','))
+            yield from self.theme.stylesheets
         else:
             yield 'default.css'
 
@@ -286,13 +285,15 @@ def init_highlighter(self) -> None:
         if self.config.pygments_style is not None:
             style = self.config.pygments_style
         elif self.theme:
-            style = self.theme.get_config('theme', 'pygments_style', 'none')
+            # From the ``pygments_style`` theme setting
+            style = self.theme.pygments_style_default or 'none'
         else:
             style = 'sphinx'
         self.highlighter = PygmentsBridge('html', style)
 
         if self.theme:
-            dark_style = self.theme.get_config('theme', 'pygments_dark_style', None)
+            # From the ``pygments_dark_style`` theme setting
+            dark_style = self.theme.pygments_style_dark
         else:
             dark_style = None
 
@@ -960,13 +961,11 @@ def add_sidebars(self, pagename: str, ctx: dict) -> None:
         def has_wildcard(pattern: str) -> bool:
             return any(char in pattern for char in '*?[')
 
-        sidebars = None
         matched = None
         customsidebar = None
 
         # default sidebars settings for selected theme
-        if theme_default_sidebars := self.theme.get_config('theme', 'sidebars', None):
-            sidebars = [name.strip() for name in theme_default_sidebars.split(',')]
+        sidebars = list(self.theme.sidebar_templates)
 
         # user sidebar settings
         html_sidebars = self.get_builder_config('sidebars', 'html')
@@ -985,7 +984,7 @@ def has_wildcard(pattern: str) -> bool:
                 matched = pattern
                 sidebars = patsidebars
 
-        if sidebars is None:
+        if len(sidebars) == 0:
             # keep defaults
             pass
 

sphinx/builders/linkcheck.py

@@ -29,7 +29,7 @@
 from sphinx.util.nodes import get_node_line
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterator
+    from collections.abc import Iterator
     from typing import Any, Callable
 
     from requests import Response
@@ -224,7 +224,7 @@ def __init__(self, config: Config) -> None:
         self.to_ignore: list[re.Pattern[str]] = list(map(re.compile,
                                                          self.config.linkcheck_ignore))
 
-    def check(self, hyperlinks: dict[str, Hyperlink]) -> Generator[CheckResult, None, None]:
+    def check(self, hyperlinks: dict[str, Hyperlink]) -> Iterator[CheckResult]:
         self.invoke_threads()
 
         total_links = 0

sphinx/builders/singlehtml.py

@@ -41,8 +41,7 @@ def get_outdated_docs(self) -> str | list[str]:  # type: ignore[override]
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         if docname in self.env.all_docs:
             # all references are on the same page...
-            return self.config.root_doc + self.out_suffix + \
-                '#document-' + docname
+            return '#document-' + docname
         else:
             # chances are this is a html_additional_page
             return docname + self.out_suffix

sphinx/config.py

@@ -359,14 +359,14 @@ def convert_overrides(self, name: str, value: str) -> Any:
 
     @staticmethod
     def pre_init_values() -> None:
-        # method only retained for compatability
+        # method only retained for compatibility
         pass
         # warnings.warn(
         #     'Config.pre_init_values() will be removed in Sphinx 9.0 or later',
         #     RemovedInSphinx90Warning, stacklevel=2)
 
     def init_values(self) -> None:
-        # method only retained for compatability
+        # method only retained for compatibility
         self._report_override_warnings()
         # warnings.warn(
         #     'Config.init_values() will be removed in Sphinx 9.0 or later',

sphinx/domains/c/_symbol.py

@@ -11,7 +11,7 @@
 from sphinx.util import logging
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterator
+    from collections.abc import Iterator
 
     from typing_extensions import Self
 
@@ -248,7 +248,7 @@ def _find_named_symbols(self, ident: ASTIdentifier,
             Symbol.debug_print("recurseInAnon:    ", recurseInAnon)
             Symbol.debug_print("searchInSiblings: ", searchInSiblings)
 
-        def candidates() -> Generator[Symbol, None, None]:
+        def candidates() -> Iterator[Symbol]:
             s = self
             if Symbol.debug_lookup:
                 Symbol.debug_print("searching in self:")

sphinx/domains/cpp/_symbol.py

@@ -17,7 +17,7 @@
 from sphinx.util import logging
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterator
+    from collections.abc import Iterator
 
     from sphinx.environment import BuildEnvironment
 
@@ -237,7 +237,7 @@ def get_all_symbols(self) -> Iterator[Any]:
             yield from sChild.get_all_symbols()
 
     @property
-    def children_recurse_anon(self) -> Generator[Symbol, None, None]:
+    def children_recurse_anon(self) -> Iterator[Symbol]:
         for c in self._children:
             yield c
             if not c.identOrOp.is_anon():
@@ -347,7 +347,7 @@ def matches(s: Symbol) -> bool:
                     return False
             return True
 
-        def candidates() -> Generator[Symbol, None, None]:
+        def candidates() -> Iterator[Symbol]:
             s = self
             if Symbol.debug_lookup:
                 Symbol.debug_print("searching in self:")

sphinx/environment/__init__.py

@@ -23,7 +23,7 @@
 from sphinx.util.osutil import canon_path, os_path
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterator
+    from collections.abc import Iterator
     from pathlib import Path
 
     from docutils import nodes
@@ -524,7 +524,7 @@ def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str],
 
         return added, changed, removed
 
-    def check_dependents(self, app: Sphinx, already: set[str]) -> Generator[str, None, None]:
+    def check_dependents(self, app: Sphinx, already: set[str]) -> Iterator[str]:
         to_rewrite: list[str] = []
         for docnames in self.events.emit('env-get-updated', self):
             to_rewrite.extend(docnames)

sphinx/ext/apidoc.py

@@ -32,7 +32,7 @@
 from sphinx.util.template import ReSTRenderer
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Sequence
+    from collections.abc import Iterator, Sequence
 
 logger = logging.getLogger(__name__)
 
@@ -214,7 +214,7 @@ def is_skipped_module(filename: str, opts: Any, _excludes: Sequence[re.Pattern[s
 
 
 def walk(rootpath: str, excludes: Sequence[re.Pattern[str]], opts: Any,
-         ) -> Generator[tuple[str, list[str], list[str]], None, None]:
+         ) -> Iterator[tuple[str, list[str], list[str]]]:
     """Walk through the directory and list files and subdirectories up."""
     followlinks = getattr(opts, 'followlinks', False)
     includeprivate = getattr(opts, 'includeprivate', False)

sphinx/ext/autodoc/importer.py

@@ -25,7 +25,7 @@
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Generator, Mapping
+    from collections.abc import Callable, Iterator, Mapping
     from types import ModuleType
     from typing import Any
 
@@ -38,7 +38,7 @@ def _filter_enum_dict(
     enum_class: type[Enum],
     attrgetter: Callable[[Any, str, Any], Any],
     enum_class_dict: Mapping[str, object],
-) -> Generator[tuple[str, type, Any], None, None]:
+) -> Iterator[tuple[str, type, Any]]:
     """Find the attributes to document of an enumeration class.
 
     The output consists of triplets ``(attribute name, defining class, value)``

sphinx/ext/autodoc/mock.py

@@ -14,7 +14,7 @@
 from sphinx.util.inspect import isboundmethod, safe_getattr
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterator, Sequence
+    from collections.abc import Iterator, Sequence
 
 logger = logging.getLogger(__name__)
 
@@ -137,7 +137,7 @@ def invalidate_caches(self) -> None:
 
 
 @contextlib.contextmanager
-def mock(modnames: list[str]) -> Generator[None, None, None]:
+def mock(modnames: list[str]) -> Iterator[None]:
     """Insert mock modules during context::
 
     with mock(['target.module.name']):

sphinx/ext/viewcode.py

@@ -22,7 +22,7 @@
 from sphinx.util.nodes import make_refnode
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterable
+    from collections.abc import Iterable, Iterator
 
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
@@ -239,7 +239,7 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
     return True
 
 
-def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], None, None]:
+def collect_pages(app: Sphinx) -> Iterator[tuple[str, dict[str, Any], str]]:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
         return

sphinx/testing/fixtures.py

@@ -14,7 +14,7 @@
 from sphinx.testing.util import SphinxTestApp, SphinxTestAppWrapperForSkipBuilding
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Generator
+    from collections.abc import Callable, Iterator
     from pathlib import Path
     from typing import Any
 
@@ -147,7 +147,7 @@ def app(
     app_params: tuple[dict, dict],
     make_app: Callable,
     shared_result: SharedResult,
-) -> Generator[SphinxTestApp, None, None]:
+) -> Iterator[SphinxTestApp]:
     """
     Provides the 'sphinx.application.Sphinx' object
     """
@@ -183,7 +183,7 @@ def warning(app: SphinxTestApp) -> StringIO:
 
 
 @pytest.fixture()
-def make_app(test_params: dict, monkeypatch: Any) -> Generator[Callable, None, None]:
+def make_app(test_params: dict, monkeypatch: Any) -> Iterator[Callable]:
     """
     Provides make_app function to initialize SphinxTestApp instance.
     if you want to initialize 'app' in your test function. please use this
@@ -289,7 +289,7 @@ def sphinx_test_tempdir(tmp_path_factory: Any) -> Path:
 
 
 @pytest.fixture()
-def rollback_sysmodules() -> Generator[None, None, None]:  # NoQA: PT004
+def rollback_sysmodules() -> Iterator[None]:  # NoQA: PT004
     """
     Rollback sys.modules to its value before testing to unload modules
     during tests.