Add autosectionlabel_full_reference configuration variable

CHANGES.rst

@@ -15,6 +15,8 @@ Deprecated
 Features added
 --------------
 
+* #13076: Add autosectionlabel_full_reference configuration variable.
+
 Bugs fixed
 ----------
 

doc/usage/extensions/autosectionlabel.rst

@@ -25,9 +25,11 @@ 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 by
 default. The ``autosectionlabel_prefix_document`` configuration variable can be
 used to make headings which appear multiple times but in different documents
-unique. Also the ``autosectionlabel_full_reference`` configuration variable can
-help ensure the generated refereences are unique across a document with similar
-section names at different levels.
+unique.
+
+Use the :conf:`autosectionlabel_full_reference` configuration variable
+to guarantee that the generated references are unique across a document
+with similar section names at different levels.
 
 
 Configuration
@@ -56,8 +58,12 @@ Configuration
    :type: :code-py:`bool`
    :default: :code-py:`False`
 
+.. versionadded:: 8.2
+
    True to make each section label include all the parent sections separated by
-   a colon. For example::
+   a colon. For instance, if the following appears in document ``index.rst``:
+
+   .. code-block:: rst
 
       Title
       =====
@@ -68,7 +74,7 @@ Configuration
       Sub Section
       ~~~~~~~~~~~
 
-   Then the reference of the third level section is
+   The reference of the third level section ("Sub Section") will be
    ``index:Title:Section:Sub Section``.
 
 Debugging

sphinx/ext/autosectionlabel.py

@@ -9,7 +9,7 @@
 import sphinx
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.nodes import clean_astext, make_id
+from sphinx.util.nodes import clean_astext, make_id, traverse_parent
 
 if TYPE_CHECKING:
     from docutils.nodes import Node
@@ -20,7 +20,7 @@
 logger = logging.getLogger(__name__)
 
 
-def get_node_depth(node: Node) -> int:
+def _get_node_depth(node: Node) -> int:
     i = 0
     cur_node = node
     while cur_node.parent != node.document:
@@ -29,43 +29,57 @@
     return i
 
 
-def get_node_parents(node: Node) -> list[str]:
+def _find_node_parents(node: Node) -> list[str]:
     parents = []
-    cur_node = node
-    while cur_node.parent != node.document:
-        cur_node = cur_node.parent
-        title = cast(nodes.title, cur_node[0])
+    for pnode in traverse_parent(node.parent, nodes.section):
+        title = cast(nodes.title, pnode[0])
         ref_name = getattr(title, 'rawsource', title.astext())
         parents.append(ref_name)
+
     return parents
 
 
-def register_sections_as_label(app: Sphinx, document: Node) -> None:
+def register_sections_as_label(app: Sphinx, doctree: nodes.document) -> None:
     domain = app.env.domains.standard_domain
-    for node in document.findall(nodes.section):
+    id_prefix = None
+
+    settings = doctree.settings
+    for node in doctree.findall(nodes.section):
         if (app.config.autosectionlabel_maxdepth and
-                get_node_depth(node) >= app.config.autosectionlabel_maxdepth):
+                _get_node_depth(node) >= app.config.autosectionlabel_maxdepth):
             continue
+
         labelid = node['ids'][0]
         docname = app.env.docname
         title = cast(nodes.title, node[0])
         ref_name = getattr(title, 'rawsource', title.astext())
+
         if app.config.autosectionlabel_prefix_document:
             if app.config.autosectionlabel_full_reference:
-                id_array = get_node_parents(node)
+                id_array = _find_node_parents(node)
                 id_array.append(docname)
                 id_array.reverse()
                 id_array.append(ref_name)
-                name = nodes.fully_normalize_name(':'.join(id_array))
-                labelid = make_id(app.env, node.document, '', '.'.join(id_array))
+                # replace id_prefix temporarily
+                id_prefix = settings.id_prefix
+                settings.id_prefix = '.'.join(id_array)
+
+                labelid = make_id(app.env, doctree, '', '.'.join(id_array))
+                node['ids'][0] = labelid
+                doctree.ids[labelid] = labelid
+                name = nodes.fully_normalize_name(labelid.replace('.', ':'))
+
+                # restore id_prefix
+                settings.id_prefix = id_prefix
             else:
-                name = nodes.fully_normalize_name(docname + ':' + ref_name)
+                name = nodes.fully_normalize_name(f'{docname}:{ref_name}')
         else:
             name = nodes.fully_normalize_name(ref_name)
+
         sectname = clean_astext(title)
 
-        logger.debug(__('section "%s" gets labeled as "%s"'),
-                     ref_name, name,
+        logger.debug(__('section "%s" gets labeled as "%s" with id as "%s" and prefix is "%s"'),
+                     ref_name, name, labelid, id_prefix,
                      location=node, type='autosectionlabel', subtype=docname)
         if name in domain.labels:
             logger.warning(__('duplicate label %s, other instance in %s'),
@@ -77,9 +91,9 @@
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_config_value('autosectionlabel_prefix_document', False, 'env')
+    app.add_config_value('autosectionlabel_prefix_document', False, 'env', bool)
     app.add_config_value('autosectionlabel_maxdepth', None, 'env')
-    app.add_config_value('autosectionlabel_full_reference', False, 'env')
+    app.add_config_value('autosectionlabel_full_reference', False, 'env', bool)
     app.connect('doctree-read', register_sections_as_label)
 
     return {

sphinx/util/nodes.py

@@ -597,7 +597,11 @@
             node_id = None  # fallback to None
 
     while node_id is None or node_id in document.ids:
-        node_id = idformat % env.new_serialno(prefix)
+        node_id = _make_id(idformat % env.new_serialno(prefix))
+
+    logger.debug(__('NODE "%s" gets term "%s" with ID format "%s" and prefix is "%s" and ids is "s"'),
+                 node_id, term, idformat, prefix,# document.ids,
+                 location=document, type='make_id')
 
     return node_id
 

sphinx/writers/latex.py

@@ -490,7 +490,9 @@ def astext(self) -> str:
         return self.render('latex.tex.jinja', self.elements)
 
     def hypertarget(self, id: str, withdoc: bool = True, anchor: bool = True) -> str:
-        if withdoc:
+        if self.config.autosectionlabel_full_reference:
+            pass
+        elif withdoc:
             id = self.curfilestack[-1] + ':' + id
         escaped_id = self.idescape(id)
         return (r'\phantomsection' if anchor else '') + r'\label{%s}' % escaped_id
@@ -1971,9 +1973,12 @@ def visit_reference(self, node: Element) -> None:
             if hashindex == -1:
                 # reference to the document
                 id = uri[1:] + '::doc'
+            elif self.config.autosectionlabel_full_reference:
+                id = uri[hashindex + 1:]
             else:
                 # reference to a label
                 id = uri[1:].replace('#', ':')
+
             self.body.append(self.hyperlink(id))
             if (
                 len(node)

sphinx/writers/texinfo.py

@@ -550,7 +550,8 @@ def get_short_id(self, id: str) -> str:
     def add_anchor(self, id: str, node: Node) -> None:
         if id.startswith('index-'):
             return
-        id = self.curfilestack[-1] + ':' + id
+        if not self.config.autosectionlabel_full_reference:
+            id = self.curfilestack[-1] + ':' + id
         eid = self.escape_id(id)
         sid = self.get_short_id(id)
         for id in (eid, sid):

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

@@ -1,3 +1,6 @@
 extensions = ['sphinx.ext.autosectionlabel']
 autosectionlabel_prefix_document = True
 autosectionlabel_full_reference = True
+latex_documents = [
+    ('index', 'test.tex', '', 'Sphinx', 'report')
+]

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

@@ -1,32 +1,30 @@
 Introduction of Sphinx
 ======================
 
-Installation
-============
 
-For Windows users
------------------
+Directives
+----------
 
-Windows
-^^^^^^^
 
-Command
-'''''''
+Installation
+============
+
+.. include:: windows.rst
 
 For UNIX users
 --------------
 
 Linux
 ^^^^^
 
-Command
-'''''''
+Command1
+''''''''
 
 FreeBSD
 ^^^^^^^
 
-Command
-'''''''
+2nd Command
+'''''''''''
 
 This one's got an apostrophe
 ----------------------------
@@ -35,14 +33,17 @@ This one's got an apostrophe
 References
 ==========
 
-* :ref:`index:Introduction of Sphinx`
+* :ref:`index:Introduction-of-Sphinx`
 * :ref:`index:Installation`
-* :ref:`index:Installation:For Windows users`
-* :ref:`index:Installation:For Windows users:Windows`
-* :ref:`index:Installation:For Windows users:Windows:Command`
-* :ref:`index:Installation:For UNIX users`
-* :ref:`index:Installation:For UNIX users:Linux`
-* :ref:`index:Installation:For UNIX users:Linux:Command`
-* :ref:`index:Installation:For UNIX users:FreeBSD`
-* :ref:`index:Installation:For UNIX users:FreeBSD:Command`
-* :ref:`index:Installation:This one's got an apostrophe`
+* :ref:`index:Installation:For-Windows-users`
+* :ref:`index:Installation:For-Windows-users:Windows`
+* :ref:`index:Installation:For-Windows-users:Windows:Command`
+* :ref:`index:Installation:For-Windows-users:Windows:Command0`
+* :ref:`index:Installation:For-Windows-users:Windows:Command1`
+* :ref:`index:Installation:For-UNIX-users`
+* :ref:`index:Installation:For-UNIX-users:Linux`
+* :ref:`index:Installation:For-UNIX-users:Linux:Command1`
+* :ref:`index:Installation:For-UNIX-users:FreeBSD`
+* :ref:`index:Installation:For-UNIX-users:FreeBSD:2nd-Command`
+* :ref:`index:Installation:This-one-s-got-an-apostrophe`
+

tests/roots/test-ext-autosectionlabel-full-reference/windows.rst

@@ -0,0 +1,27 @@
+For Windows users
+-----------------
+
+Windows
+^^^^^^^
+
+Command
+'''''''
+
+Command
+'''''''
+
+This has the same name as the section before but a unique label id is required.
+
+Command
+'''''''
+
+This has the same name as the two sections before but a unique label id is required.
+
+Local References
+^^^^^^^^^^^^^^^^
+
+* :ref:`windows:For-Windows-users`
+* :ref:`windows:For-Windows-users:Windows`
+* :ref:`windows:For-Windows-users:Windows:Command`
+* :ref:`windows:For-Windows-users:Windows:Command0`
+* :ref:`windows:For-Windows-users:Windows:Command1`