Examples#

Due to Limitation, the extension can not work with all roles, so we list all use cases we have tested.

Nested Parse#

See also

:parsed_literal:`https://example.com``	`https://example.com`
:parsed_literal:`\|release\|``	`1.0`
:parsed_literal:`RFC: :rfc:\`1459\``	`RFC: RFC 1459`

Note

For nested roles, note that the backquote ` needs to be escaped by \\.

Cross references: `:ref:`, `:doc:` and more…#

comboroles_roles = {
    'literal_ref': ['literal', 'ref'],
    'literal_doc': ['literal', 'doc'],
}

:ref:`composite-roles`	Composite Roles
:literal_ref:`composite-roles`	`Composite Roles`
:doc:`changelog`	Change Log
:literal_doc:`changelog`	`Change Log`

The “python” Domain#

comboroles_roles = {
   'strong_pycls': ['strong', 'py:class'],
}

:py:class:`str`	`str`
:strong_pycls:`str`	`str`

Works with other Extensions#

`sphinx.ext.extlink`#

sphinx.ext.extlink is a Sphinx builtin extension to create shorten external links.

Assume that we have the following configuration, extlink creates the issue role, then comboroles creates a literal_issue role based on it:

extlinks = {
    'issue': ('https://github.com/sphinx-notes/comboroles/issues/%s', '💬%s'),
}

comboroles_roles = {
    'literal_issue': ['literal', 'issue'],
}

:issue:`new`	💬new
:literal_issue:`new`	`💬new`

See also

https://github.com/sphinx-doc/sphinx/issues/11745

`sphinxnotes.strike`#

sphinxnotes.strike is an extension that adds strikethrough text support to Sphinx.

comboroles_roles = {
   'literal_strike': ['literal', 'strike'],
}

:strike:`text`	text
:literal_strike:`text`	`text`