Fix duplicate label warnings for included files (#14413)

Author: FazeelUsmani

sphinx/domains/std/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import operator
+import os.path
 import re
 from copy import copy
 from typing import TYPE_CHECKING, cast
@@ -778,6 +779,7 @@ class StandardDomain(Domain):
             'modindex': ('py-modindex', ''),
             'search': ('search', ''),
         },
+        'labels_source': {},  # labelname -> source file path
     }
 
     # labelname -> docname, sectionname
@@ -893,6 +895,12 @@ def labels(self) -> dict[str, tuple[str, str, str]]:
     def anonlabels(self) -> dict[str, tuple[str, str]]:
         return self.data.setdefault('anonlabels', {})  # labelname -> docname, labelid
 
+    @property
+    def labels_source(self) -> dict[str, str]:
+        return self.data.setdefault(
+            'labels_source', {}
+        )  # labelname -> source file path
+
     def clear_doc(self, docname: str) -> None:
         to_remove1 = [
             key for key, (fn, _l) in self.progoptions.items() if fn == docname
@@ -911,6 +919,7 @@ def clear_doc(self, docname: str) -> None:
         to_remove3 = [key for key, (fn, _l, _l) in self.labels.items() if fn == docname]
         for key3 in to_remove3:
             del self.labels[key3]
+            self.labels_source.pop(key3, None)
 
         to_remove3 = [key for key, (fn, _l) in self.anonlabels.items() if fn == docname]
         for key3 in to_remove3:
@@ -933,6 +942,9 @@ def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> Non
         for key, data in otherdata['anonlabels'].items():
             if data[0] in docnames:
                 self.anonlabels[key] = data
+        for key, data in otherdata.get('labels_source', {}).items():
+            if key in self.labels:
+                self.labels_source[key] = data
 
     def process_doc(
         self, env: BuildEnvironment, docname: str, document: nodes.document
@@ -957,12 +969,30 @@ def process_doc(
                 # link and object descriptions
                 continue
             if name in self.labels:
-                logger.warning(
-                    __('duplicate label %s, other instance in %s'),
-                    name,
-                    env.doc2path(self.labels[name][0]),
-                    location=node,
-                )
+                current_source = getattr(node, 'source', None)
+                existing_source = self.labels_source.get(name)
+                existing_docname = self.labels[name][0]
+
+                # Check if both labels come from the same source file
+                if current_source and existing_source:
+                    current_norm = os.path.normcase(os.path.normpath(current_source))
+                    existing_norm = os.path.normcase(os.path.normpath(existing_source))
+                    same_source = current_norm == existing_norm
+                else:
+                    same_source = False
+
+                if same_source:
+                    # Same source file included in multiple documents.
+                    # Prefer the including document for proper figure numbering.
+                    if existing_docname not in env.included.get(docname, set()):
+                        continue
+                else:
+                    logger.warning(
+                        __('duplicate label %s, other instance in %s'),
+                        name,
+                        env.doc2path(existing_docname),
+                        location=node,
+                    )
             self.anonlabels[name] = docname, labelid
             if node.tagname == 'section':
                 title = cast('nodes.title', node[0])
@@ -991,6 +1021,9 @@ def process_doc(
                         # anonymous-only labels
                         continue
             self.labels[name] = docname, labelid, sectname
+            node_source = getattr(node, 'source', None)
+            if node_source:
+                self.labels_source[name] = node_source
 
     def add_program_option(
         self, program: str | None, name: str, docname: str, labelid: str

tests/roots/test-numfig-include-duplicate/conf.py

@@ -0,0 +1,3 @@
+project = 'test-numfig-include-duplicate'
+exclude_patterns = ['_build']
+numfig = True

tests/roots/test-numfig-include-duplicate/doc1.rst

@@ -0,0 +1,8 @@
+Document 1
+==========
+
+.. _shared-label:
+
+.. figure:: img.png
+
+   Figure in doc1

tests/roots/test-numfig-include-duplicate/doc2.rst

@@ -0,0 +1,8 @@
+Document 2
+==========
+
+.. _shared-label:
+
+.. figure:: img.png
+
+   Figure in doc2 (DUPLICATE label from different source file)

tests/roots/test-numfig-include-duplicate/img.png

@@ -0,0 +1,7 @@
+Test duplicate labels across documents
+======================================
+
+.. toctree::
+
+   doc1
+   doc2

tests/roots/test-numfig-include-duplicate/index.rst

@@ -0,0 +1,15 @@
+.. _included-figure:
+
+.. figure:: /img.png
+
+   This is an included figure
+
+See :numref:`included-figure` for the figure above.
+
+.. _included-figure-2:
+
+.. figure:: /img.png
+
+   This is another included figure
+
+See :numref:`included-figure-2` for figure 2.

tests/roots/test-numfig-include/_includes/figures.rst

@@ -0,0 +1,3 @@
+project = 'test-numfig-include'
+exclude_patterns = ['_build']  # NOT excluding _includes to test include-aware duplicate handling
+numfig = True

tests/roots/test-numfig-include/conf.py

@@ -0,0 +1,16 @@
+Test numfig with include
+========================
+
+This document tests that :numref: works with figures in included files.
+
+.. include:: _includes/figures.rst
+
+Reference to included figure: :numref:`included-figure`
+
+Reference to local figure: :numref:`local-figure`
+
+.. _local-figure:
+
+.. figure:: img.png
+
+   This is a local figure