Added autosectionlabel_prefix_document config option.

doc/ext/autosectionlabel.rst

@@ -22,4 +22,18 @@ For example::
 
 
 Internally, this extension generates the labels for each section.  If same
-section names are used in whole of document, any one is used for a target.
+section names are used in whole of document, any one is used for a target by
+default. The ``autosectionlabel_prefix_document`` configuration variable can be
+used to make headings which appear multiple times but in different documents
+unique.
+
+Configuration
+-------------
+
+.. confval:: autosectionlabel_prefix_document
+
+   True to prefix each section label with the name of the document it is in,
+   followed by a colon. For example, ``index:Introduction`` for a section
+   called ``Introduction`` that appears in document ``index.rst``.  Useful for
+   avoiding ambiguity when the same section heading appears in different
+   documents.

sphinx/ext/autosectionlabel.py

@@ -20,9 +20,12 @@ def register_sections_as_label(app, document):
     labels = app.env.domaindata['std']['labels']
     anonlabels = app.env.domaindata['std']['anonlabels']
     for node in document.traverse(nodes.section):
-        name = nodes.fully_normalize_name(node[0].astext())
         labelid = node['ids'][0]
         docname = app.env.docname
+        if app.config.autosectionlabel_prefix_document:
+            name = nodes.fully_normalize_name(docname + ':' + node[0].astext())
+        else:
+            name = nodes.fully_normalize_name(node[0].astext())
         sectname = clean_astext(node[0])
 
         if name in labels:
@@ -35,4 +38,5 @@ def register_sections_as_label(app, document):
 
 
 def setup(app):
+    app.add_config_value('autosectionlabel_prefix_document', False, 'env')
     app.connect('doctree-read', register_sections_as_label)

tests/roots/test-ext-autosectionlabel-prefix-document/conf.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+extensions = ['sphinx.ext.autosectionlabel']
+master_doc = 'index'
+autosectionlabel_prefix_document = True

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

@@ -0,0 +1,25 @@
+=========================================
+test-ext-autosectionlabel-prefix-document
+=========================================
+
+
+Introduce of Sphinx
+===================
+
+Installation
+============
+
+For Windows users
+-----------------
+
+For UNIX users
+--------------
+
+
+References
+==========
+
+* :ref:`index:Introduce of Sphinx`
+* :ref:`index:Installation`
+* :ref:`index:For Windows users`
+* :ref:`index:For UNIX users`

tests/test_ext_autosectionlabel.py

@@ -34,3 +34,9 @@ def test_autosectionlabel_html(app, status, warning):
     html = ('<li><a class="reference internal" href="#for-unix-users">'
             '<span class="std std-ref">For UNIX users</span></a></li>')
     assert re.search(html, content, re.S)
+
+
+# Re-use test definition from above, just change the test root directory
+@pytest.mark.sphinx('html', testroot='ext-autosectionlabel-prefix-document')
+def test_autosectionlabel_prefix_document_html(app, status, warning):
+    return test_autosectionlabel_html(app, status, warning)