Usage

Composite Roles

Users can create composite roles by adding an item to configuration item ⚙️comboroles_roles. For example:

comboroles_roles = {
    'strong_literal': ['strong', 'literal'],
}

:strong_literal:`bold code`

bold code

The above configuration creates a composite role strong_literal, and consists of two existing roles strong and literal. The Interpreted Text of strong_literal (in this case, it is “bold code”) will be interpreted first by role literal and then by strong. In pseudo reStructuredText, it looks like:

:strong:`:literal:`bold code``

That is why we said we implement nested inline markups in a sense.

Hint

Here are some role names of commonly used markups:

Usage	Role
emphasis	emphasis
strong emphasis	strong
inline literals	literal
sub script	sub
super script	sup

Nested Parse

Normally, Interpreted Text will not be parsed, but will be passed directly to the role. Once the nested_parse flag of ⚙️comboroles_roles is enabled, Interpreted Text of composite roles will be parsed, and then passed to the role. For example:

comboroles_roles = {
    'parsed_literal': (['literal'], True),
}

``**bold code**``	**bold code**
:parsed_literal:`**bold code**`	bold code

The above configuration creates a composite role parsed_literal with nested_parse enabled, so the text “**bold code**” can be parsed.

Further, hyperlinks, substitutions, and even roles inside interpreted text can be parsed too, see Nested Parse for more details.

Works with other Extensions

Moved to Examples.

Limitation

Due to internal implementation, the extension can only used to composite simple roles and may CRASH Sphinx when compositing complex roles. DO NOT report to Sphinx first if it crashes, please report to here 💬new instead.

n