Add warning for multiple toc parents found

CHANGES.rst

@@ -99,9 +99,9 @@ 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.
+* #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
 
 

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,19 @@ 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(
+                __(f"document is referenced in multiple toctrees: {parents}, "
+                   f"selecting: {max(parents)} <- {doc}"),
+                location=doc, type='toc',
+                subtype='multiple_toc_parents'
+            )

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):