Add tests and update CHANGES

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: Ensure deterministic resolution of global toctree in parallel builds
+  when document is included in multiple toctrees by choosing lexicographically
+  greatest parent document.
+  Patch by A. Rafey Khan
 
 
 Testing

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_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")