Allow users to provide a custom label for duplicate names

doc/usage/extensions/autosectionlabel.rst

@@ -30,6 +30,27 @@ default. The ``autosectionlabel_prefix_document`` configuration variable can be
 used to make headings which appear multiple times but in different documents
 unique.
 
+If a heading appears multiple times in a document, custom labels can be used to
+refer duplicate sections.
+
+For example::
+
+    Section Title
+    -------------
+
+    This is the text of the first section.
+
+    It refers to the section title, see :ref:`Section Title`.
+
+    .. _duplicate_section_title:
+
+    Section Title
+    -------------
+
+    This is the text of the second section.
+
+    It refers to the corresponding section title, see :ref:`duplicate_section_title`.
+
 
 Configuration
 -------------

sphinx/ext/autosectionlabel.py

@@ -42,6 +42,8 @@ def register_sections_as_label(app: Sphinx, document: Node) -> None:
         docname = app.env.current_document.docname
         title = cast('nodes.title', node[0])
         ref_name = getattr(title, 'rawsource', title.astext())
+        if len(node['ids']) > 1 and node['ids'][-1].startswith('id'):
+            continue
         if app.config.autosectionlabel_prefix_document:
             name = nodes.fully_normalize_name(docname + ':' + ref_name)
         else:

tests/roots/test-ext-autosectionlabel-prefix-document/index.rst

@@ -9,6 +9,11 @@ Introduce of Sphinx
 Installation
 ============
 
+.. _custom-label:
+
+Installation
+============
+
 For Windows users
 -----------------
 
@@ -30,6 +35,7 @@ References
 
 * :ref:`index:Introduce of Sphinx`
 * :ref:`index:Installation`
+* :ref:`custom-label`
 * :ref:`index:For Windows users`
 * :ref:`index:For UNIX users`
 * :ref:`index:Linux`

tests/roots/test-ext-autosectionlabel/index.rst

@@ -9,6 +9,11 @@ Introduce of Sphinx
 Installation
 ============
 
+.. _custom-label:
+
+Installation
+============
+
 For Windows users
 -----------------
 
@@ -30,6 +35,7 @@ References
 * :ref:`test-ext-autosectionlabel`
 * :ref:`Introduce of Sphinx`
 * :ref:`Installation`
+* :ref:`custom-label`
 * :ref:`For Windows users`
 * :ref:`For UNIX users`
 * :ref:`Linux`

tests/test_extensions/test_ext_autosectionlabel.py

@@ -28,6 +28,12 @@ def test_autosectionlabel_html(app: SphinxTestApp) -> None:
     )
     assert re.search(html, content, re.DOTALL)
 
+    html = (
+        '<li><p><a class="reference internal" href="#custom-label">'
+        '<span class="std std-ref">Installation</span></a></p></li>'
+    )
+    assert re.search(html, content, re.DOTALL)
+
     html = (
         '<li><p><a class="reference internal" href="#for-windows-users">'
         '<span class="std std-ref">For Windows users</span></a></p></li>'