Fix #1286, #2099: Add `sphinx.ext.autosectionlabel` extension to allow reference sections using its title

CHANGES

@@ -66,6 +66,8 @@ Features added
 * #2300: enhance autoclass:: to use the docstring of __new__ if __init__ method's is missing
   of empty
 * #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for numfig feature
+* #1286, #2099: Add ``sphinx.ext.autosectionlabel`` extension to allow reference
+  sections using its title. Thanks to Tadhg O'Higgins.
 
 Bugs fixed
 ----------

doc/ext/autosectionlabel.rst

@@ -0,0 +1,25 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title
+==============================================================================
+
+.. module:: sphinx.ext.autosectionlabel
+   :synopsis: Allow reference section its title.
+
+.. versionadded:: 1.4
+
+This extension allows you to refer sections its title.  This affects to the
+reference role (:rst:role:`ref`).
+
+For example::
+
+    A Plain Title
+    -------------
+
+    This is the text of the section.
+
+    It refers to the section title, see :ref:`A Plain Title`.
+
+
+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.

doc/extensions.rst

@@ -19,6 +19,7 @@ These extensions are built in and can be activated by respective entries in the
 .. toctree::
 
    ext/autodoc
+   ext/autosectionlabel
    ext/autosummary
    ext/coverage
    ext/doctest

sphinx/ext/autosectionlabel.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.ext.autosectionlabel
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Allow reference sections by :ref: role using its title.
+
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from docutils import nodes
+from sphinx.util.nodes import clean_astext
+
+
+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
+        sectname = clean_astext(node[0])
+
+        if name in labels:
+            app.env.warn_node('duplicate label %s, ' % name + 'other instance '
+                              'in ' + app.env.doc2path(labels[name][0]), node)
+
+        anonlabels[name] = docname, labelid
+        labels[name] = docname, labelid, sectname
+
+
+def setup(app):
+    app.connect('doctree-read', register_sections_as_label)

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

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

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

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

tests/test_ext_autosectionlabel.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""
+    test_ext_autosectionlabel
+    ~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Test sphinx.ext.autosectionlabel extension.
+
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import re
+
+from util import with_app
+
+
+@with_app('html', testroot='ext-autosectionlabel')
+def test_autosectionlabel_html(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').text()
+    html = ('<li><a class="reference internal" href="#introduce-of-sphinx">'
+            '<span class=".*?">Introduce of Sphinx</span></a></li>')
+    assert re.search(html, content, re.S)
+
+    html = ('<li><a class="reference internal" href="#installation">'
+            '<span class="std std-ref">Installation</span></a></li>')
+    assert re.search(html, content, re.S)
+
+    html = ('<li><a class="reference internal" href="#for-windows-users">'
+            '<span class="std std-ref">For Windows users</span></a></li>')
+    assert re.search(html, content, re.S)
+
+    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)