Environment.file_to_rebuild: pickle to sorted list instead of set

pyproject.toml

@@ -70,6 +70,7 @@ dependencies = [
     "imagesize>=1.3",
     "requests>=2.30.0",
     "packaging>=23.0",
+    "sortedcontainers>=2.4.0",
     "tomli>=2; python_version < '3.11'",
     "colorama>=0.4.6; sys_platform == 'win32'",
 ]

sphinx/environment/__init__.py

@@ -66,7 +66,7 @@
 
 # This is increased every time an environment attribute is added
 # or changed to properly invalidate pickle files.
-ENV_VERSION = 63
+ENV_VERSION = 64
 
 # config status
 CONFIG_UNSET = -1
@@ -232,7 +232,7 @@ def __init__(self, app: Sphinx) -> None:
         # docname -> list of toctree includefiles
         self.toctree_includes: dict[str, list[str]] = {}
         # docname -> set of files (containing its TOCs) to rebuild too
-        self.files_to_rebuild: dict[str, set[str]] = {}
+        self.files_to_rebuild: dict[str, list[str]] = {}
         # docnames that have :glob: toctrees
         self.glob_toctrees: set[str] = set()
         # docnames that have :numbered: toctrees
@@ -747,7 +747,7 @@ def check_consistency(self) -> None:
         """Do consistency checks."""
         included = set().union(*self.included.values())
         for docname in sorted(self.all_docs):
-            if docname not in self.files_to_rebuild:
+            if docname not in self.files_to_rebuild:  # TODO: SortedList (?)
                 if docname == self.config.root_doc:
                     # the master file is not included anywhere ;)
                     continue

sphinx/environment/adapters/toctree.py

@@ -6,6 +6,7 @@
 
 from docutils import nodes
 from docutils.nodes import Element, Node
+from sortedcontainers import SortedList
 
 from sphinx import addnodes
 from sphinx.locale import __
@@ -36,7 +37,9 @@ def note_toctree(env: BuildEnvironment, docname: str, toctreenode: addnodes.toct
     for include_file in include_files:
         # note that if the included file is rebuilt, this one must be
         # too (since the TOC of the included file could have changed)
-        env.files_to_rebuild.setdefault(include_file, set()).add(docname)
+        fnlist = SortedList(env.files_to_rebuild.get(include_file, []))
+        fnlist.add(docname)
+        env.files_to_rebuild[include_file] = list(fnlist)
     env.toctree_includes.setdefault(docname, []).extend(include_files)
 
 

sphinx/environment/collectors/toctree.py

@@ -5,6 +5,7 @@
 from typing import TYPE_CHECKING, TypeVar, cast
 
 from docutils import nodes
+from sortedcontainers import SortedList
 
 from sphinx import addnodes
 from sphinx.environment.adapters.toctree import note_toctree
@@ -37,9 +38,12 @@ def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.glob_toctrees.discard(docname)
         env.numbered_toctrees.discard(docname)
 
-        for subfn, fnset in list(env.files_to_rebuild.items()):
-            fnset.discard(docname)
-            if not fnset:
+        for subfn, fnlist in list(env.files_to_rebuild.items()):
+            try:
+                fnlist.remove(docname)
+            except ValueError:
+                pass
+            if not fnlist:
                 del env.files_to_rebuild[subfn]
 
     def merge_other(self, app: Sphinx, env: BuildEnvironment, docnames: set[str],
@@ -54,8 +58,10 @@ def merge_other(self, app: Sphinx, env: BuildEnvironment, docnames: set[str],
             if docname in other.numbered_toctrees:
                 env.numbered_toctrees.add(docname)
 
-        for subfn, fnset in other.files_to_rebuild.items():
-            env.files_to_rebuild.setdefault(subfn, set()).update(fnset & set(docnames))
+        for subfn, other_fnlist in other.files_to_rebuild.items():
+            fnlist = SortedList(env.files_to_rebuild.get(subfn, []))
+            fnlist.update(frozenset(other_fnlist) & docnames)
+            env.files_to_rebuild[subfn] = list(fnlist)
 
     def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
         """Build a TOC from the doctree and store it in the inventory."""

tests/test_environment/test_environment_toctree.py

@@ -144,9 +144,9 @@ def test_process_doc(app):
     # other collections
     assert app.env.toc_num_entries['index'] == 6
     assert app.env.toctree_includes['index'] == ['foo', 'bar', 'baz']
-    assert app.env.files_to_rebuild['foo'] == {'index'}
-    assert app.env.files_to_rebuild['bar'] == {'index'}
-    assert app.env.files_to_rebuild['baz'] == {'index'}
+    assert app.env.files_to_rebuild['foo'] == ['index']
+    assert app.env.files_to_rebuild['bar'] == ['index']
+    assert app.env.files_to_rebuild['baz'] == ['index']
     assert app.env.glob_toctrees == set()
     assert app.env.numbered_toctrees == {'index'}