Add option_parse_variable_part config value.

Support parsing of "variable part" for option directives similarly
to samp roles.

Fixes: sphinx-doc#9965.

doc/usage/configuration.rst

@@ -700,6 +700,14 @@ General configuration
 
     .. versionadded:: 3.0
 
+.. confval:: option_parse_variable_part
+
+   Default is ``False``.
+   Similarly to ``samp`` role, support parsing of "variable part" of a literal text.
+   For example, in ``..option: -foption={TYPE}``,
+   the part ``TYPE`` would be emphasized.
+
+   .. versionadded:: 4.4
 
 .. _intl-options:
 

doc/usage/restructuredtext/domains.rst

@@ -1708,6 +1708,9 @@ There is a set of directives allowing documenting command-line programs:
    referenceable by :rst:role:`option` (in the example case, you'd use something
    like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```).
 
+   Use :confval:`option_parse_variable_part` for parsing of
+   "variable part" of a literal text (similarly to ``samp`` directive).
+
    ``cmdoption`` directive is a deprecated alias for the ``option`` directive.
 
 .. rst:directive:: .. envvar:: name

sphinx/config.py

@@ -148,6 +148,7 @@ class Config:
         'smartquotes_excludes': ({'languages': ['ja'],
                                   'builders': ['man', 'text']},
                                  'env', []),
+        'option_parse_variable_part': (False, 'env', []),
     }
 
     def __init__(self, config: Dict[str, Any] = {}, overrides: Dict[str, Any] = {}) -> None:

sphinx/domains/std.py

@@ -24,7 +24,7 @@
 from sphinx.directives import ObjectDescription
 from sphinx.domains import Domain, ObjType
 from sphinx.locale import _, __
-from sphinx.roles import XRefRole
+from sphinx.roles import EmphasizedLiteral, XRefRole
 from sphinx.util import docname_join, logging, ws_re
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import clean_astext, make_id, make_refnode
@@ -43,6 +43,8 @@
 # RE for grammar tokens
 token_re = re.compile(r'`((~?\w*:)?\w+)`', re.U)
 
+samp_role = EmphasizedLiteral()
+
 
 class GenericObject(ObjectDescription[str]):
     """
@@ -201,7 +203,10 @@ def handle_signature(self, sig: str, signode: desc_signature) -> str:
             if count:
                 signode += addnodes.desc_addname(', ', ', ')
             signode += addnodes.desc_name(optname, optname)
-            signode += addnodes.desc_addname(args, args)
+            if self.env.config.option_parse_variable_part:
+                signode += samp_role.parse(args)
+            else:
+                signode += addnodes.desc_addname(args, args)
             if not count:
                 firstname = optname
                 signode['allnames'] = [optname]

tests/roots/test-root/objects.txt

@@ -194,6 +194,15 @@ Link to :option:`perl +p`, :option:`--ObjC++`, :option:`--plugin.option`, :optio
 
 Link to :option:`hg commit` and :option:`git commit -p`.
 
+.. option:: --abi={TYPE}
+
+.. option:: --test={WHERE}-{COUNT}
+
+.. option:: --wrap=\{\{value\}\}
+
+.. option:: -allowable_client {client_name}
+
+Foo bar.
 
 User markup
 ===========

tests/test_build_html.py

@@ -1673,3 +1673,24 @@ def test_html_signaturereturn_icon(app):
     content = (app.outdir / 'index.html').read_text()
 
     assert ('<span class="sig-return-icon">&#x2192;</span>' in content)
+
+
+@pytest.mark.sphinx('html', testroot='root',
+                    confoverrides={'option_parse_variable_part': True})
+def test_option_with_variable_part(app, status, warning):
+    app.build()
+    content = (app.outdir / 'objects.html').read_text()
+    assert '<em><span class="pre">TYPE</span></em>' in content
+    assert '{TYPE}' not in content
+    assert ('<em><span class="pre">WHERE</span></em><span class="pre">-</span>'
+            '<em><span class="pre">COUNT</span></em>' in content)
+    assert '<span class="pre">={{value}}</span>' in content
+
+
+@pytest.mark.sphinx('html', testroot='root')
+def test_option_with_variable_part_default(app, status, warning):
+    app.build()
+    content = (app.outdir / 'objects.html').read_text()
+    assert '<span class="pre">={TYPE}</span>' in content
+    assert '<span class="pre">={WHERE}-{COUNT}</span></span>' in content
+    assert '<span class="pre">{client_name}</span>' in content