From a9659a0ee59f5727f675b9b6111aa601f7571fb9 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sun, 11 Aug 2024 19:23:36 +0100
Subject: [PATCH 1/8] Mark ``Builder.write()`` as final

---
 CHANGES.rst                                   |  6 ++++
 doc/_static/diagrams/sphinx_build_flow.dot    | 11 +++----
 .../diagrams/sphinx_core_events_flow.dot      |  4 +--
 doc/extdev/builderapi.rst                     |  5 ++--
 sphinx/builders/__init__.py                   | 30 ++++++++++++-------
 sphinx/builders/changes.py                    |  6 ++--
 sphinx/builders/dummy.py                      |  3 --
 sphinx/builders/epub3.py                      |  4 ++-
 sphinx/builders/gettext.py                    |  3 --
 sphinx/builders/html/__init__.py              |  8 ++---
 sphinx/builders/latex/__init__.py             | 12 ++++----
 sphinx/builders/manpage.py                    |  4 ++-
 sphinx/builders/singlehtml.py                 |  9 +++---
 sphinx/builders/texinfo.py                    |  8 ++---
 sphinx/builders/text.py                       |  4 +--
 sphinx/builders/xml.py                        |  4 +--
 sphinx/ext/coverage.py                        |  2 +-
 sphinx/ext/doctest.py                         | 10 ++-----
 18 files changed, 72 insertions(+), 61 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 596259e74db..85690bc5b7c 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -42,6 +42,12 @@ Bugs fixed
 * #12587: Do not warn when potential ambiguity detected during Intersphinx
   resolution occurs due to duplicate targets that differ case-insensitively.
   Patch by James Addison.
+* #12639: :py:meth:`Builder.write` is typed as ``final``, meaning that the
+  :event:`write-started` event may be relied upon by extensions.
+  A new :py:meth:`Builder.write_documents` method has been added to
+  control how documents are written.
+  This is intended for builders that do not output a file for each document.
+  Patch by Adam Turner.
 
 Testing
 -------
diff --git a/doc/_static/diagrams/sphinx_build_flow.dot b/doc/_static/diagrams/sphinx_build_flow.dot
index 0e736f53733..59fbdd0d1e2 100644
--- a/doc/_static/diagrams/sphinx_build_flow.dot
+++ b/doc/_static/diagrams/sphinx_build_flow.dot
@@ -27,10 +27,6 @@ digraph build {
     "Builder.build_update":p1 -> "Builder.build";
 
     "Builder.build" -> "Builder.read";
-    "Builder.write" [
-        shape=record
-        label = "<p1> Builder.write | Builder._write_serial | Builder._write_parallel"
-    ];
     "Builder.build" -> "Builder.write";
     "Builder.build" -> "Builder.finish";
 
@@ -39,8 +35,13 @@ digraph build {
 
     "Builder.write":p1 -> "Builder.prepare_writing";
     "Builder.write":p1 -> "Builder.copy_assets";
-    "Builder.write":p1 -> "Builder.write_doc";
+    "Builder.write_documents" [
+        shape=record
+        label = "<p1> Builder.write_documents | Builder._write_serial | Builder._write_parallel"
+    ];
+    "Builder.write":p1 -> "Builder.write_documents";
 
+    "Builder.write_documents":p1 -> "Builder.write_doc";
     "Builder.write_doc" -> "Builder.get_relative_uri";
 
     "Builder.get_relative_uri" -> "Builder.get_target_uri";
diff --git a/doc/_static/diagrams/sphinx_core_events_flow.dot b/doc/_static/diagrams/sphinx_core_events_flow.dot
index 1499e6ba8fc..4ef46c1a67f 100644
--- a/doc/_static/diagrams/sphinx_core_events_flow.dot
+++ b/doc/_static/diagrams/sphinx_core_events_flow.dot
@@ -83,9 +83,9 @@ digraph events {
 
     // during write phase
     "write-started"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
-    "Builder.build":write -> "write-started";
     "Builder.write" [label = "Builder.write()"]
     "Builder.build":write -> "Builder.write";
+    "Builder.write" -> "write-started";
     write_each_doc [shape="ellipse", label="for updated"];
     "Builder.write" -> write_each_doc;
     "ReferenceResolver" [
@@ -120,6 +120,6 @@ digraph events {
     {rank=same; "env-get-outdated" "env-before-read-docs" "env-get-updated"};
     {rank=same; "env-purge-doc" "source-read" "doctree-read", "merge_each_process"};
     {rank=same; "env-updated" "env-check-consistency"};
-    {rank=same; "env-merge-info" "write-started" "Builder.write"};
+    {rank=same; "env-merge-info" "Builder.write"};
     {rank=max; "build-finished"};
 }
diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst
index 9259aaa735f..2545498c7f8 100644
--- a/doc/extdev/builderapi.rst
+++ b/doc/extdev/builderapi.rst
@@ -39,20 +39,21 @@ Builder API
    .. automethod:: read
    .. automethod:: read_doc
    .. automethod:: write_doctree
+   .. automethod:: write
 
    .. rubric:: Overridable Methods
 
    These must be implemented in builder sub-classes:
 
    .. automethod:: get_outdated_docs
-   .. automethod:: prepare_writing
    .. automethod:: write_doc
    .. automethod:: get_target_uri
 
    These methods can be overridden in builder sub-classes:
 
    .. automethod:: init
-   .. automethod:: write
+   .. automethod:: write_documents
+   .. automethod:: prepare_writing
    .. automethod:: copy_assets
    .. automethod:: get_relative_uri
    .. automethod:: finish
diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py
index 3c5313afe41..f2c5be3f7b0 100644
--- a/sphinx/builders/__init__.py
+++ b/sphinx/builders/__init__.py
@@ -41,7 +41,7 @@
 from sphinx import roles  # NoQA: F401  isort:skip
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Sequence
+    from collections.abc import Iterable, Sequence, Set
 
     from docutils.nodes import Node
 
@@ -585,6 +585,7 @@ def write_doctree(
         if _cache:
             self.env._write_doc_doctree_cache[docname] = doctree
 
+    @final
     def write(
         self,
         build_docnames: Iterable[str] | None,
@@ -597,7 +598,7 @@ def write(
 
         if build_docnames is None or build_docnames == ['__all__']:
             # build_all
-            build_docnames = self.env.found_docs
+            build_docnames = self.env.all_docs
         if method == 'update':
             # build updated ones as well
             docnames = set(build_docnames) | set(updated_docnames)
@@ -606,11 +607,12 @@ def write(
         logger.debug(__('docnames to write: %s'), ', '.join(sorted(docnames)))
 
         # add all toctree-containing files that may have changed
-        for docname in list(docnames):
+        extra = {self.config.root_doc}
+        for docname in docnames:
             for tocdocname in self.env.files_to_rebuild.get(docname, set()):
                 if tocdocname in self.env.found_docs:
-                    docnames.add(tocdocname)
-        docnames.add(self.config.root_doc)
+                    extra.add(tocdocname)
+        docnames |= extra
 
         with progress_message(__('preparing documents')):
             self.prepare_writing(docnames)
@@ -618,13 +620,21 @@ def write(
         with progress_message(__('copying assets'), nonl=False):
             self.copy_assets()
 
+        self.write_documents(docnames)
+
+    def write_documents(self, docnames: Set[str]) -> None:
+        """Write all documents in *docnames*.
+
+        This method can be overridden if a builder does not create
+        output files for each document.
+        """
+        sorted_docnames = sorted(docnames)
         if self.parallel_ok:
             # number of subprocesses is parallel-1 because the main process
             # is busy loading doctrees and doing write_doc_serialized()
-            self._write_parallel(sorted(docnames),
-                                 nproc=self.app.parallel - 1)
+            self._write_parallel(sorted_docnames, nproc=self.app.parallel - 1)
         else:
-            self._write_serial(sorted(docnames))
+            self._write_serial(sorted_docnames)
 
     def _write_serial(self, docnames: Sequence[str]) -> None:
         with logging.pending_warnings():
@@ -674,9 +684,9 @@ def on_chunk_done(args: list[tuple[str, nodes.document]], result: None) -> None:
         tasks.join()
         logger.info('')
 
-    def prepare_writing(self, docnames: set[str]) -> None:
+    def prepare_writing(self, docnames: Set[str]) -> None:
         """A place where you can add logic before :meth:`write_doc` is run"""
-        raise NotImplementedError
+        pass
 
     def copy_assets(self) -> None:
         """Where assets (images, static files, etc) are copied before writing"""
diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py
index afc5f064b22..d6bb2b5c2a5 100644
--- a/sphinx/builders/changes.py
+++ b/sphinx/builders/changes.py
@@ -4,7 +4,7 @@
 
 import html
 from os import path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, cast
 
 from sphinx import package_dir
 from sphinx.builders import Builder
@@ -17,6 +17,8 @@
 from sphinx.util.osutil import ensuredir, os_path
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
 
@@ -47,7 +49,7 @@ def get_outdated_docs(self) -> str:
         'versionremoved': 'removed',
     }
 
-    def write(self, *ignored: Any) -> None:
+    def write_documents(self, _docnames: Set[str]) -> None:
         version = self.config.version
         domain = cast(ChangeSetDomain, self.env.get_domain('changeset'))
         libchanges: dict[str, list[tuple[str, str, int]]] = {}
diff --git a/sphinx/builders/dummy.py b/sphinx/builders/dummy.py
index 05b7e568791..f8a4c298d30 100644
--- a/sphinx/builders/dummy.py
+++ b/sphinx/builders/dummy.py
@@ -29,9 +29,6 @@ def get_outdated_docs(self) -> set[str]:
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         return ''
 
-    def prepare_writing(self, docnames: set[str]) -> None:
-        pass
-
     def write_doc(self, docname: str, doctree: nodes.document) -> None:
         pass
 
diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py
index 004821b6e85..49a850bad70 100644
--- a/sphinx/builders/epub3.py
+++ b/sphinx/builders/epub3.py
@@ -21,6 +21,8 @@
 from sphinx.util.osutil import make_filename
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
 
@@ -118,7 +120,7 @@ def content_metadata(self) -> dict[str, Any]:
         metadata['epub_version'] = self.config.epub_version
         return metadata
 
-    def prepare_writing(self, docnames: set[str]) -> None:
+    def prepare_writing(self, docnames: Set[str]) -> None:
         super().prepare_writing(docnames)
 
         writing_mode = self.config.epub_writing_mode
diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py
index f1f7d7fa920..26c15e13e39 100644
--- a/sphinx/builders/gettext.py
+++ b/sphinx/builders/gettext.py
@@ -149,9 +149,6 @@ def get_target_uri(self, docname: str, typ: str | None = None) -> str:
     def get_outdated_docs(self) -> set[str]:
         return self.env.found_docs
 
-    def prepare_writing(self, docnames: set[str]) -> None:
-        return
-
     def compile_catalogs(self, catalogs: set[CatalogInfo], message: str) -> None:
         return
 
diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
index 2fa5f360a95..014db0003eb 100644
--- a/sphinx/builders/html/__init__.py
+++ b/sphinx/builders/html/__init__.py
@@ -63,7 +63,7 @@
 from sphinx.writers.html5 import HTML5Translator
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator, Set
+    from collections.abc import Iterator, Set
     from typing import TypeAlias
 
     from docutils.nodes import Node
@@ -468,7 +468,7 @@ def render_partial(self, node: Node | None) -> dict[str, str]:
         self._publisher.publish()
         return self._publisher.writer.parts
 
-    def prepare_writing(self, docnames: set[str]) -> None:
+    def prepare_writing(self, docnames: Set[str]) -> None:
         # create the search indexer
         self.indexer = None
         if self.search:
@@ -982,9 +982,9 @@ def post_process_images(self, doctree: Node) -> None:
                 node.replace_self(reference)
                 reference.append(node)
 
-    def load_indexer(self, docnames: Iterable[str]) -> None:
+    def load_indexer(self, docnames: Set[str]) -> None:
         assert self.indexer is not None
-        keep = set(self.env.all_docs) - set(docnames)
+        keep = set(self.env.all_docs) - docnames
         try:
             searchindexfn = path.join(self.outdir, self.searchindex_filename)
             if self.indexer_dumps_unicode:
diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py
index f19d66edbc9..9b0cfe17188 100644
--- a/sphinx/builders/latex/__init__.py
+++ b/sphinx/builders/latex/__init__.py
@@ -38,7 +38,7 @@
 from docutils import nodes  # isort:skip
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Iterable, Set
 
     from docutils.nodes import Node
 
@@ -268,13 +268,17 @@ def write_stylesheet(self) -> None:
             f.write('% Its contents depend on pygments_style configuration variable.\n\n')
             f.write(highlighter.get_stylesheet())
 
+    def prepare_writing(self, docnames: Set[str]) -> None:
+        self.init_document_data()
+        self.write_stylesheet()
+
     def copy_assets(self) -> None:
         self.copy_support_files()
 
         if self.config.latex_additional_files:
             self.copy_latex_additional_files()
 
-    def write(self, *ignored: Any) -> None:
+    def write_documents(self, _docnames: Set[str]) -> None:
         docwriter = LaTeXWriter(self)
         with warnings.catch_warnings():
             warnings.filterwarnings('ignore', category=DeprecationWarning)
@@ -285,10 +289,6 @@ def write(self, *ignored: Any) -> None:
                 components=(docwriter,),
                 read_config_files=True).get_default_values()
 
-        self.init_document_data()
-        self.write_stylesheet()
-        self.copy_assets()
-
         for entry in self.document_data:
             docname, targetname, title, author, themename = entry[:5]
             theme = self.themes.get(themename)
diff --git a/sphinx/builders/manpage.py b/sphinx/builders/manpage.py
index 0070b043f3d..e904bf8b906 100644
--- a/sphinx/builders/manpage.py
+++ b/sphinx/builders/manpage.py
@@ -20,6 +20,8 @@
 from sphinx.writers.manpage import ManualPageTranslator, ManualPageWriter
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from sphinx.application import Sphinx
     from sphinx.config import Config
     from sphinx.util.typing import ExtensionMetadata
@@ -51,7 +53,7 @@ def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         return ''
 
     @progress_message(__('writing'))
-    def write(self, *ignored: Any) -> None:
+    def write_documents(self, _docnames: Set[str]) -> None:
         docwriter = ManualPageWriter(self)
         with warnings.catch_warnings():
             warnings.filterwarnings('ignore', category=DeprecationWarning)
diff --git a/sphinx/builders/singlehtml.py b/sphinx/builders/singlehtml.py
index d222184b52f..7546288d08a 100644
--- a/sphinx/builders/singlehtml.py
+++ b/sphinx/builders/singlehtml.py
@@ -16,6 +16,8 @@
 from sphinx.util.nodes import inline_all_toctrees
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
@@ -152,11 +154,8 @@ def get_doc_context(self, docname: str, body: str, metatags: str) -> dict[str, A
             'display_toc': display_toc,
         }
 
-    def write(self, *ignored: Any) -> None:
-        docnames = self.env.all_docs
-
-        with progress_message(__('preparing documents')):
-            self.prepare_writing(docnames)  # type: ignore[arg-type]
+    def write_documents(self, _docnames: Set[str]) -> None:
+        self.prepare_writing(self.env.all_docs.keys())
 
         with progress_message(__('assembling single document'), nonl=False):
             doctree = self.assemble_doctree()
diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py
index b62160f8ee3..a38868640b7 100644
--- a/sphinx/builders/texinfo.py
+++ b/sphinx/builders/texinfo.py
@@ -25,7 +25,7 @@
 from sphinx.writers.texinfo import TexinfoTranslator, TexinfoWriter
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Iterable, Set
 
     from docutils.nodes import Node
 
@@ -70,7 +70,7 @@ def get_relative_uri(self, from_: str, to: str, typ: str | None = None) -> str:
         # ignore source path
         return self.get_target_uri(to, typ)
 
-    def init_document_data(self) -> None:
+    def prepare_writing(self, _docnames: Set[str]) -> None:
         preliminary_document_data = [list(x) for x in self.config.texinfo_documents]
         if not preliminary_document_data:
             logger.warning(__('no "texinfo_documents" config value found; no documents '
@@ -89,9 +89,7 @@ def init_document_data(self) -> None:
                 docname = docname[:-5]
             self.titles.append((docname, entry[2]))
 
-    def write(self, *ignored: Any) -> None:
-        self.init_document_data()
-        self.copy_assets()
+    def write_documents(self, _docnames: Set[str]) -> None:
         for entry in self.document_data:
             docname, targetname, title, author = entry[:4]
             targetname += '.texi'
diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py
index 92544034c49..294f35110bd 100644
--- a/sphinx/builders/text.py
+++ b/sphinx/builders/text.py
@@ -18,7 +18,7 @@
 from sphinx.writers.text import TextTranslator, TextWriter
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Set
 
     from docutils import nodes
 
@@ -64,7 +64,7 @@ def get_outdated_docs(self) -> Iterator[str]:
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         return ''
 
-    def prepare_writing(self, docnames: set[str]) -> None:
+    def prepare_writing(self, docnames: Set[str]) -> None:
         self.writer = TextWriter(self)
 
     def write_doc(self, docname: str, doctree: nodes.document) -> None:
diff --git a/sphinx/builders/xml.py b/sphinx/builders/xml.py
index 6be0ff8d6e4..a9310b603ce 100644
--- a/sphinx/builders/xml.py
+++ b/sphinx/builders/xml.py
@@ -20,7 +20,7 @@
 from sphinx.writers.xml import PseudoXMLWriter, XMLWriter
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Set
 
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
@@ -68,7 +68,7 @@ def get_outdated_docs(self) -> Iterator[str]:
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         return docname
 
-    def prepare_writing(self, docnames: set[str]) -> None:
+    def prepare_writing(self, docnames: Set[str]) -> None:
         self.writer = self._writer_class(self)
 
     def write_doc(self, docname: str, doctree: nodes.document) -> None:
diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py
index 5ecc1670959..beb9a5647a8 100644
--- a/sphinx/ext/coverage.py
+++ b/sphinx/ext/coverage.py
@@ -192,7 +192,7 @@ def init(self) -> None:
     def get_outdated_docs(self) -> str:
         return 'coverage overview'
 
-    def write(self, *ignored: Any) -> None:
+    def write_documents(self, _docnames: Set[str]) -> None:
         self.py_undoc: dict[str, dict[str, Any]] = {}
         self.py_undocumented: dict[str, Set[str]] = {}
         self.py_documented: dict[str, Set[str]] = {}
diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py
index 19f01f4cab6..676e357c1f3 100644
--- a/sphinx/ext/doctest.py
+++ b/sphinx/ext/doctest.py
@@ -27,7 +27,7 @@
 from sphinx.util.osutil import relpath
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Sequence
+    from collections.abc import Callable, Set
 
     from docutils.nodes import Element, Node, TextElement
 
@@ -355,13 +355,9 @@ def s(v: int) -> str:
         if self.total_failures or self.setup_failures or self.cleanup_failures:
             self.app.statuscode = 1
 
-    def write(self, build_docnames: Iterable[str] | None, updated_docnames: Sequence[str],
-              method: str = 'update') -> None:
-        if build_docnames is None:
-            build_docnames = sorted(self.env.all_docs)
-
+    def write_documents(self, docnames: Set[str]) -> None:
         logger.info(bold('running tests...'))
-        for docname in build_docnames:
+        for docname in docnames:
             # no need to resolve the doctree
             doctree = self.env.get_doctree(docname)
             self.test_doc(docname, doctree)

From c2c3463aae7497f443c1839f1bb286aa10df69f3 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sun, 11 Aug 2024 19:46:04 +0100
Subject: [PATCH 2/8] warnings

---
 CHANGES.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 85690bc5b7c..c49423a0365 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -42,9 +42,9 @@ Bugs fixed
 * #12587: Do not warn when potential ambiguity detected during Intersphinx
   resolution occurs due to duplicate targets that differ case-insensitively.
   Patch by James Addison.
-* #12639: :py:meth:`Builder.write` is typed as ``final``, meaning that the
+* #12639: :py:meth:`.Builder.write` is typed as ``final``, meaning that the
   :event:`write-started` event may be relied upon by extensions.
-  A new :py:meth:`Builder.write_documents` method has been added to
+  A new :py:meth:`.Builder.write_documents` method has been added to
   control how documents are written.
   This is intended for builders that do not output a file for each document.
   Patch by Adam Turner.

From 559f8103e0bc54602e6789dcfc4cb0e879328721 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sun, 11 Aug 2024 19:51:33 +0100
Subject: [PATCH 3/8] PR number

---
 CHANGES.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index c49423a0365..349a9f6cc04 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -42,7 +42,7 @@ Bugs fixed
 * #12587: Do not warn when potential ambiguity detected during Intersphinx
   resolution occurs due to duplicate targets that differ case-insensitively.
   Patch by James Addison.
-* #12639: :py:meth:`.Builder.write` is typed as ``final``, meaning that the
+* #12767: :py:meth:`.Builder.write` is typed as ``final``, meaning that the
   :event:`write-started` event may be relied upon by extensions.
   A new :py:meth:`.Builder.write_documents` method has been added to
   control how documents are written.

From 0016a8ccbb3036c10a4f14580c3612014a5e0c34 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Thu, 10 Oct 2024 10:17:39 +0100
Subject: [PATCH 4/8] =?UTF-8?q?B=C3=A9n=C3=A9dikt's=20comments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 sphinx/builders/html/__init__.py | 2 +-
 sphinx/ext/doctest.py            | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
index 014db0003eb..88ce3415691 100644
--- a/sphinx/builders/html/__init__.py
+++ b/sphinx/builders/html/__init__.py
@@ -984,7 +984,7 @@ def post_process_images(self, doctree: Node) -> None:
 
     def load_indexer(self, docnames: Set[str]) -> None:
         assert self.indexer is not None
-        keep = set(self.env.all_docs) - docnames
+        keep = set(self.env.all_docs).difference(docnames)
         try:
             searchindexfn = path.join(self.outdir, self.searchindex_filename)
             if self.indexer_dumps_unicode:
diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py
index 676e357c1f3..a06a785f46f 100644
--- a/sphinx/ext/doctest.py
+++ b/sphinx/ext/doctest.py
@@ -357,7 +357,7 @@ def s(v: int) -> str:
 
     def write_documents(self, docnames: Set[str]) -> None:
         logger.info(bold('running tests...'))
-        for docname in docnames:
+        for docname in sorted(docnames):
             # no need to resolve the doctree
             doctree = self.env.get_doctree(docname)
             self.test_doc(docname, doctree)

From beb92f5e6e9e8a9bbc5b85f8ad0c4e3661bb81e8 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Thu, 10 Oct 2024 10:23:42 +0100
Subject: [PATCH 5/8] =?UTF-8?q?B=C3=A9n=C3=A9dikt's=20comments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 sphinx/builders/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py
index 4e292156a19..68c62d9d125 100644
--- a/sphinx/builders/__init__.py
+++ b/sphinx/builders/__init__.py
@@ -677,7 +677,7 @@ def write(
 
         if build_docnames is None or build_docnames == ['__all__']:
             # build_all
-            build_docnames = self.env.all_docs
+            build_docnames = self.env.found_docs
         if method == 'update':
             # build updated ones as well
             docnames = set(build_docnames) | set(updated_docnames)

From f37ccc2c0e79254fce3030daeb01fa7ca470dea4 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Thu, 10 Oct 2024 10:24:39 +0100
Subject: [PATCH 6/8] lint

---
 sphinx/builders/html/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
index 6956e7643c5..a38d12b60a8 100644
--- a/sphinx/builders/html/__init__.py
+++ b/sphinx/builders/html/__init__.py
@@ -64,7 +64,7 @@
 from sphinx.writers.html5 import HTML5Translator
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Set
     from typing import TypeAlias
 
     from docutils.nodes import Node

From 98b6a50d21f70bc48431995dc0b120bd637623a9 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Thu, 10 Oct 2024 10:26:19 +0100
Subject: [PATCH 7/8] whitespace

---
 CHANGES.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index ef25001f794..604f378d634 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -146,7 +146,6 @@ Bugs fixed
   and ensure deterministic resolution of global toctree in parallel builds
   by choosing the lexicographically greatest parent document.
   Patch by A. Rafey Khan
-
 * #12767: :py:meth:`.Builder.write` is typed as ``final``, meaning that the
   :event:`write-started` event may be relied upon by extensions.
   A new :py:meth:`.Builder.write_documents` method has been added to
@@ -154,6 +153,7 @@ Bugs fixed
   This is intended for builders that do not output a file for each document.
   Patch by Adam Turner.
 
+
 Testing
 -------
 

From 731f1bcf7007a1bd562159dd53022ab029a85d1e Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Thu, 10 Oct 2024 15:45:50 +0100
Subject: [PATCH 8/8] Chris' comments

---
 doc/extdev/builderapi.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst
index b1a8b45fcb9..ccc0da8c5bd 100644
--- a/doc/extdev/builderapi.rst
+++ b/doc/extdev/builderapi.rst
@@ -41,7 +41,7 @@ Builder API
    .. automethod:: write_doctree
    .. automethod:: write
 
-   .. rubric:: Overridable Methods
+   .. rubric:: Abstract Methods
 
    These must be implemented in builder sub-classes:
 
@@ -49,6 +49,8 @@ Builder API
    .. automethod:: write_doc
    .. automethod:: get_target_uri
 
+   .. rubric:: Overridable Methods
+
    These methods can be overridden in builder sub-classes:
 
    .. automethod:: init