Merge pull request #6063 from tk0miya/4261_autosectionlabel_max_depth

Add autosectionlabel_max_depth config option

CHANGES

@@ -192,6 +192,8 @@ Features added
 * #5196: linkcheck also checks remote images exist
 * #5924: githubpages: create CNAME file for custom domains when
   :confval:`html_baseurl` set
+* #4261: autosectionlabel: restrict the labeled sections by new config value;
+  :confval:`autosectionlabel_maxdepth`
 
 
 Bugs fixed

doc/usage/extensions/autosectionlabel.rst

@@ -38,3 +38,10 @@ Configuration
    called ``Introduction`` that appears in document ``index.rst``.  Useful for
    avoiding ambiguity when the same section heading appears in different
    documents.
+
+.. confval:: autosectionlabel_maxdepth
+
+   If set, autosectionlabel chooses the sections for labeling by its depth. For
+   example, when set 1 to ``autosectionlabel_maxdepth``, labels are generated
+   only for top level sections, and deeper sections are not labeled.  It
+   defaults to ``None`` (disabled).

sphinx/ext/autosectionlabel.py

@@ -30,11 +30,23 @@ if False:
     from sphinx.application import Sphinx  # NOQA
 
 
+def get_node_depth(node):
+    i = 0
+    cur_node = node
+    while cur_node.parent != node.document:
+        cur_node = cur_node.parent
+        i += 1
+    return i
+
+
 def register_sections_as_label(app, document):
     # type: (Sphinx, nodes.Node) -> None
     labels = app.env.domaindata['std']['labels']
     anonlabels = app.env.domaindata['std']['anonlabels']
     for node in document.traverse(nodes.section):
+        if (app.config.autosectionlabel_maxdepth and
+                get_node_depth(node) >= app.config.autosectionlabel_maxdepth):
+            continue
         labelid = node['ids'][0]
         docname = app.env.docname
         title = cast(nodes.title, node[0])
@@ -57,6 +69,7 @@ def register_sections_as_label(app, document):
 def setup(app):
     # type: (Sphinx) -> Dict[str, Any]
     app.add_config_value('autosectionlabel_prefix_document', False, 'env')
+    app.add_config_value('autosectionlabel_maxdepth', None, 'env')
     app.connect('doctree-read', register_sections_as_label)
 
     return {

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

@@ -15,6 +15,12 @@ For Windows users
 For UNIX users
 --------------
 
+Linux
+^^^^^
+
+FreeBSD
+^^^^^^^
+
 This one's got an apostrophe
 ----------------------------
 
@@ -26,4 +32,6 @@ References
 * :ref:`index:Installation`
 * :ref:`index:For Windows users`
 * :ref:`index:For UNIX users`
+* :ref:`index:Linux`
+* :ref:`index:FreeBSD`
 * :ref:`index:This one's got an apostrophe`

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

@@ -15,15 +15,23 @@ For Windows users
 For UNIX users
 --------------
 
+Linux
+^^^^^
+
+FreeBSD
+^^^^^^^
+
 This one's got an apostrophe
 ----------------------------
 
-
 References
 ==========
 
+* :ref:`test-ext-autosectionlabel`
 * :ref:`Introduce of Sphinx`
 * :ref:`Installation`
 * :ref:`For Windows users`
 * :ref:`For UNIX users`
+* :ref:`Linux`
+* :ref:`FreeBSD`
 * :ref:`This one's got an apostrophe`

tests/test_ext_autosectionlabel.py

@@ -18,7 +18,7 @@ from sphinx.util import docutils
 @pytest.mark.skipif(docutils.__version_info__ < (0, 13),
                     reason='docutils-0.13 or above is required')
 @pytest.mark.sphinx('html', testroot='ext-autosectionlabel')
-def test_autosectionlabel_html(app, status, warning):
+def test_autosectionlabel_html(app, status, warning, skipped_labels=False):
     app.builder.build_all()
 
     content = (app.outdir / 'index.html').text()
@@ -38,6 +38,14 @@ def test_autosectionlabel_html(app, status, warning):
             '<span class="std std-ref">For UNIX users</span></a></p></li>')
     assert re.search(html, content, re.S)
 
+    html = ('<li><a class="reference internal" href="#linux">'
+            '<span class="std std-ref">Linux</span></a></li>')
+    assert re.search(html, content, re.S)
+
+    html = ('<li><a class="reference internal" href="#freebsd">'
+            '<span class="std std-ref">FreeBSD</span></a></li>')
+    assert re.search(html, content, re.S)
+
     # for smart_quotes (refs: #4027)
     html = ('<li><p><a class="reference internal" '
             'href="#this-one-s-got-an-apostrophe">'
@@ -51,4 +59,33 @@ def test_autosectionlabel_html(app, status, warning):
                     reason='docutils-0.13 or above is required')
 @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)
+    test_autosectionlabel_html(app, status, warning)
+
+
+@pytest.mark.sphinx('html', testroot='ext-autosectionlabel',
+                    confoverrides={'autosectionlabel_maxdepth': 3})
+def test_autosectionlabel_maxdepth(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').text()
+
+    # depth: 1
+    html = ('<li><a class="reference internal" href="#test-ext-autosectionlabel">'
+            '<span class=".*?">test-ext-autosectionlabel</span></a></li>')
+    assert re.search(html, content, re.S)
+
+    # depth: 2
+    html = ('<li><a class="reference internal" href="#installation">'
+            '<span class="std std-ref">Installation</span></a></li>')
+    assert re.search(html, content, re.S)
+
+    # depth: 3
+    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)
+
+    # depth: 4
+    html = '<li><span class="xref std std-ref">Linux</span></li>'
+    assert re.search(html, content, re.S)
+
+    assert 'WARNING: undefined label: linux' in warning.getvalue()