Ensure deterministic resolution of toctree

CHANGES.rst

@@ -127,6 +127,11 @@ Bugs fixed
   ``SOURCE_DATE_EPOCH`` for entries that match the current system clock year,
   and disallow substitution of future years.
   Patch by James Addison and Adam Turner.
+* #12888: Add a warning when document is included in multiple toctrees
+  and ensure deterministic resolution of global toctree in parallel builds
+  by choosing the lexicographically greatest parent document.
+  Patch by A. Rafey Khan
+
 
 Testing
 -------

sphinx/builders/__init__.py

@@ -691,6 +691,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

@@ -750,6 +750,10 @@ def check_consistency(self) -> None:
                 logger.warning(
                     __("document isn't included in any toctree"), location=docname
                 )
+        # Call _check_toc_parents here rather than in  _get_toctree_ancestors()
+        # because that method is called multiple times per document and would
+        # lead to duplicate warnings.
+        _check_toc_parents(self.toctree_includes)
 
         # call check-consistency for all extensions
         self.domains._check_consistency()
@@ -782,3 +786,24 @@ 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]]) -> None:
+    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.info(
+                __(
+                    '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/alpha.rst

@@ -0,0 +1,7 @@
+Alpha
+=====
+
+.. literalinclude:: relation_graph.txt
+
+.. toctree::
+   bravo

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

@@ -0,0 +1,7 @@
+Bravo
+=====
+
+.. literalinclude:: relation_graph.txt
+
+.. toctree::
+   charlie

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

@@ -0,0 +1,4 @@
+Charlie
+=======
+
+.. literalinclude:: relation_graph.txt

tests/roots/test-toctree-multiple-parents/conf.py

@@ -0,0 +1 @@
+html_theme = 'basic'

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

@@ -0,0 +1,7 @@
+Delta
+=====
+
+.. literalinclude:: relation_graph.txt
+
+.. toctree::
+   charlie

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

@@ -0,0 +1,8 @@
+test-toctree-multiple-parents
+=============================
+
+.. literalinclude:: relation_graph.txt
+
+.. toctree::
+   alpha
+   delta

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

@@ -0,0 +1,7 @@
+     index
+    /     \
+ alpha   delta
+    \      /
+   bravo  /
+      \  /
+     charlie

tests/test_builders/test_build.py

@@ -100,6 +100,14 @@ 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)
+    assert (
+        "document is referenced in multiple toctrees: ['bravo', 'delta'], selecting: delta <- charlie"
+    ) in app.status.getvalue()
+
+
 @pytest.mark.usefixtures('_http_teapot')
 @pytest.mark.sphinx('dummy', testroot='images')
 def test_image_glob(app):

tests/test_builders/test_build_html_toctree.py

@@ -1,6 +1,7 @@
 """Test the HTML builder and check output against XPath."""
 
 import re
+from unittest.mock import patch
 
 import pytest
 
@@ -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):
+    # The 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 m:
+        # Read files in reversed order
+        _read_serial = type(app.builder)._read_serial
+        m.side_effect = lambda docnames: _read_serial(app.builder, docnames[::-1])
+        app.build()
+        # Check if charlie is a child of delta in charlie.html
+        xpath_delta_children = (
+            ".//ul[@class='current']//a[@href='delta.html']/../ul/li//a"
+        )
+        etree = cached_etree_parse(app.outdir / 'charlie.html')
+        check_xpath(etree, 'charlie.html', xpath=xpath_delta_children, check='Charlie')