allow users to provide a custom label for duplicate names

Author: n

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>'