config: Add 'link_inline_targets'

doc/usage/configuration.rst

@@ -483,6 +483,14 @@ General configuration
       The LaTeX builder obeys this setting (if :confval:`numfig` is set to
       ``True``).
 
+.. confval:: link_inline_targets
+
+   If true, inline targets will be cross-referenceable, even if they don't have
+   an explicit title. For example, when this is set, ``_`this one``` can be
+   cross-referenced using ``:ref:`this one```. Default: ``False``.
+
+   .. versionadded:: 4.4.1
+
 .. confval:: smartquotes
 
    If true, the `Docutils Smart Quotes transform`__, originally based on

doc/usage/restructuredtext/roles.rst

@@ -106,12 +106,17 @@ These roles are described with their respective domains:
 Cross-referencing arbitrary locations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. versionchanged:: 4.4.1
+
+   Added the :confval:`link_inline_targets` config option, allowing optional
+   cross-referencing of inline targets without an explicit title.
+
 .. rst:role:: ref
 
    To support cross-referencing to arbitrary locations in any document, the
    standard reST labels are used.  For this to work label names must be unique
-   throughout the entire documentation.  There are two ways in which you can
-   refer to labels:
+   throughout the entire documentation.  How you refer to a label depends on
+   where the label occurs:
 
    * If you place a label directly before a section title, you can reference to
      it with ``:ref:`label-name```.  For example::
@@ -143,9 +148,12 @@ Cross-referencing arbitrary locations
      The same works for tables that are given an explicit caption using the
      :dudir:`table` directive.
 
-   * Labels that aren't placed before a section title can still be referenced,
-     but you must give the link an explicit title, using this syntax:
-     ``:ref:`Link title <label-name>```.
+   * If a label is not placed before a section title then you have two options.
+     The usual way to do this is to give the link an explicit title, using this
+     syntax: ``:ref:`Link title <label-name>```. In this case, the label,
+     ``label-name``, must be globally unique. Alternatively, to avoid
+     duplication, you can configure :confval:`link_inline_targets` to `True`.
+     In this case, the link text becomes the label.
 
    .. note::
 

sphinx/config.py

@@ -136,6 +136,7 @@ class Config:
         'numfig': (False, 'env', []),
         'numfig_secnum_depth': (1, 'env', []),
         'numfig_format': ({}, 'env', []),  # will be initialized in init_numfig_format()
+        'link_inline_targets': (False, 'env', []),
 
         'math_number_all': (False, 'env', []),
         'math_eqref_format': (None, 'env', [str]),

sphinx/domains/std.py

@@ -763,6 +763,8 @@ def process_doc(self, env: "BuildEnvironment", docname: str, document: nodes.doc
             elif node.tagname == 'rubric':
                 sectname = clean_astext(node)
             elif node.tagname == 'target' and len(node) > 0:
+                if env.config.link_inline_targets is False:
+                    continue
                 # inline target (ex: blah _`blah` blah)
                 sectname = clean_astext(node)
             elif self.is_enumerable_node(node):

tests/test_domain_std.py

@@ -457,8 +457,18 @@ def test_labeled_rubric(app):
 
 def test_inline_target(app):
     text = "blah _`inline target` blah\n"
+    app.config.link_inline_targets = True
     restructuredtext.parse(app, text)
 
     domain = app.env.get_domain("std")
     assert 'inline target' in domain.labels
     assert domain.labels['inline target'] == ('index', 'inline-target', 'inline target')
+
+
+def test_inline_target_disabled(app):
+    text = "blah _`inline target` blah\n"
+    app.config.link_inline_targets = False
+    restructuredtext.parse(app, text)
+
+    domain = app.env.get_domain("std")
+    assert 'inline target' not in domain.labels