From 231976ff1450f60ab561db9fcbdda018c8fba782 Mon Sep 17 00:00:00 2001
From: smheidrich <smheidrich@weltenfunktion.de>
Date: Sat, 4 Feb 2017 01:23:16 +0100
Subject: [PATCH] Added autosectionlabel_prefix_document config option.

---
 doc/ext/autosectionlabel.rst                  | 16 +++++++++++-
 sphinx/ext/autosectionlabel.py                |  6 ++++-
 .../conf.py                                   |  5 ++++
 .../index.rst                                 | 25 +++++++++++++++++++
 tests/test_ext_autosectionlabel.py            |  6 +++++
 5 files changed, 56 insertions(+), 2 deletions(-)
 create mode 100644 tests/roots/test-ext-autosectionlabel-prefix-document/conf.py
 create mode 100644 tests/roots/test-ext-autosectionlabel-prefix-document/index.rst

diff --git a/doc/ext/autosectionlabel.rst b/doc/ext/autosectionlabel.rst
index 10d998075..f4a6322c3 100644
--- a/doc/ext/autosectionlabel.rst
+++ b/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.
diff --git a/sphinx/ext/autosectionlabel.py b/sphinx/ext/autosectionlabel.py
index d45ba66a6..72c7ce2e3 100644
--- a/sphinx/ext/autosectionlabel.py
+++ b/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)
diff --git a/tests/roots/test-ext-autosectionlabel-prefix-document/conf.py b/tests/roots/test-ext-autosectionlabel-prefix-document/conf.py
new file mode 100644
index 000000000..0a6491dd3
--- /dev/null
+++ b/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
diff --git a/tests/roots/test-ext-autosectionlabel-prefix-document/index.rst b/tests/roots/test-ext-autosectionlabel-prefix-document/index.rst
new file mode 100644
index 000000000..a608c5b51
--- /dev/null
+++ b/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`
diff --git a/tests/test_ext_autosectionlabel.py b/tests/test_ext_autosectionlabel.py
index 71d19e800..c3e875e9a 100644
--- a/tests/test_ext_autosectionlabel.py
+++ b/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)