Ensure deterministic resolution of toctree

CHANGES.rst

@@ -99,6 +99,10 @@ Bugs fixed
 * #12796: Enable parallel reading if requested,
   even if there are fewer than 6 documents.
   Patch by Matthias Geier.
+* #12888: Add a warning when document is included in multiple toctrees
+  and ensure deterministic resolution of global toctree in parallel builds
+  by choosing lexicographically greatest parent document.
+  Patch by A. Rafey Khan
 
 
 Testing

sphinx/builders/__init__.py

@@ -613,6 +613,9 @@ def write(
                     docnames.add(tocdocname)
         docnames.add(self.config.root_doc)
 
+        # sort to ensure deterministic toctree generation
+        self.env.toctree_includes = dict(sorted(self.env.toctree_includes.items()))
+
         with progress_message(__('preparing documents')):
             self.prepare_writing(docnames)
 

sphinx/environment/__init__.py

@@ -758,6 +758,7 @@ def check_consistency(self) -> None:
                     continue
                 logger.warning(__("document isn't included in any toctree"),
                                location=docname)
+        _check_toc_parents(self.toctree_includes)
 
         # call check-consistency for all extensions
         for domain in self.domains.values():
@@ -788,3 +789,22 @@ def _traverse_toctree(
             if sub_docname not in traversed:
                 yield sub_parent, sub_docname
                 traversed.add(sub_docname)
+
+
+def _check_toc_parents(toctree_includes:  dict[str, list[str]]):
+    toc_parents: dict[str, list[str]] = {}
+    for parent, children in toctree_includes.items():
+        for child in children:
+            toc_parents.setdefault(child, []).append(parent)
+
+    for doc, parents in sorted(toc_parents.items()):
+        if len(parents) > 1:
+            logger.warning(
+                __("document is referenced in multiple toctrees: %s, "
+                   "selecting: %s <- %s"),
+                parents,
+                max(parents),
+                doc,
+                location=doc, type='toc',
+                subtype='multiple_toc_parents'
+            )

tests/roots/test-toctree-multiple-parents/bar.rst

@@ -0,0 +1,6 @@
+Bar
+===
+.. literalinclude:: relation_graph.txt
+
+.. toctree::
+   qux

tests/roots/test-toctree-multiple-parents/baz.rst

@@ -0,0 +1,6 @@
+Baz
+===
+.. literalinclude:: relation_graph.txt
+
+.. toctree::
+   qux

tests/roots/test-toctree-multiple-parents/foo.rst

@@ -0,0 +1,6 @@
+Foo
+===
+.. literalinclude:: relation_graph.txt
+
+.. toctree::
+   bar

tests/roots/test-toctree-multiple-parents/index.rst

@@ -0,0 +1,7 @@
+test-toctree-multiple-parents
+=============================
+.. literalinclude:: relation_graph.txt
+
+.. toctree::
+   foo
+   baz

tests/roots/test-toctree-multiple-parents/qux.rst

@@ -0,0 +1,3 @@
+Qux
+===
+.. literalinclude:: relation_graph.txt

tests/roots/test-toctree-multiple-parents/relation_graph.txt

@@ -0,0 +1,7 @@
+     index
+    /     \
+   foo    baz
+    \      /
+    bar   /
+      \  /
+      qux

tests/test_builders/test_build.py

@@ -100,6 +100,15 @@ def test_numbered_circular_toctree(app):
     ) in warnings
 
 
+@pytest.mark.sphinx('text', testroot='toctree-multiple-parents')
+def test_multiple_parents_toctree(app):
+    app.build(force_all=True)
+    warnings = app.warning.getvalue()
+    assert (
+        "document is referenced in multiple toctrees: ['bar', 'baz'], selecting: baz <- qux"
+    ) in warnings
+
+
 @pytest.mark.usefixtures('_http_teapot')
 @pytest.mark.sphinx('dummy', testroot='images')
 def test_image_glob(app):

tests/test_builders/test_build_html_toctree.py

@@ -3,6 +3,7 @@
 import re
 
 import pytest
+from unittest.mock import patch
 
 from tests.test_builders.xpath_html_util import _intradocument_hyperlink_check
 from tests.test_builders.xpath_util import check_xpath
@@ -63,3 +64,24 @@ def test_numbered_toctree(app):
 def test_singlehtml_hyperlinks(app, cached_etree_parse, expect):
     app.build()
     check_xpath(cached_etree_parse(app.outdir / 'index.html'), 'index.html', *expect)
+
+
+@pytest.mark.sphinx(
+    'html',
+    testroot='toctree-multiple-parents',
+    confoverrides={'html_theme': 'alabaster'},
+)
+def test_toctree_multiple_parents(app, cached_etree_parse):
+    # Lexicographically greatest parent of the document in global toctree
+    # should be chosen regardless of the order in which files are read
+    with patch.object(app.builder, '_read_serial') as mock_read_serial:
+        # Read files in reversed order
+        _read_serial = app.builder.__class__._read_serial
+        mock_read_serial.side_effect = lambda docnames: _read_serial(
+            app.builder, list(reversed(docnames))
+        )
+        app.build()
+        # Check if qux is a child of baz in qux.html
+        xpath_baz_children = ".//ul[@class='current']//a[@href='baz.html']/../ul/li//a"
+        etree = cached_etree_parse(app.outdir / 'qux.html')
+        check_xpath(etree, 'qux.html', xpath=xpath_baz_children, check='Qux')