1.2.1. Roles

A role or “custom interpreted text role” is an inline piece of explicit markup, see Inline Markup and Explicit Markup. It signifies that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section.

The general syntax is :rolename:`content`. Like Directives, roles are extensible. Own roles can be created. They are used inside other text structures.

Docutils supports the following roles (incomplete list):

:emphasis:

emphasis – :emphasis:`emphasis` – equivalent of *emphasis*

:strong:

strong – :strong:`strong` – equivalent of **strong**

:literal:

literal – :literal:`literal` – equivalent of ``literal``

:code:

code – :code:`code` – equivalent of ``code``

:subscript:

subscript – :subscript:`subscript` – subscript text

The example

The Fibonacci numbers (without inline role for Mathematics).

1
2
3
4
.. |gE| unicode:: U+02267 .. GREATER-THAN OVER EQUAL TO

*f*\ :subscript:`n` = *f*\ :subscript:`n-1` + *f*\ :subscript:`n-2`
for *n* |gE| 3 with *f*\ :subscript:`1` = *f*\ :subscript:`2` = 1
Which gives

fn = fn-1 + fn-2 for n ≧ 3 with f1 = f2 = 1

:superscript:

superscript – :superscript:`superscript` – superscript text

The example

The elementary charge (without inline role for Mathematics).

1
2
3
.. |sdot| unicode:: U+022C5 .. DOT OPERATOR

*e* = 1.602176634 |sdot| 10\ :superscript:`-19` C
Which gives

e = 1.602176634 ⋅ 10-19 C

:math:

math – :math:`mathematic equations` – for Mathematics equations

:pep-reference:

pep-reference – :pep-reference:`pep-reference` – equivalent to :pep:`pep reference number` – for External References into the PEP index

:rfc-reference:

rfc-reference – :rfc-reference:`rfc-reference` – equivalent to :rfc:`rfc reference number` – for External References into the RFC index

:title-reference:

title-reference – :title-reference:`title-reference` – for titles of books, periodicals, and other materials

See also