Roles¶
Roles are inline markers that give a fragment of text a special meaning:
they format it, or turn it into a link.
A role is written :name:`text` in reStructuredText and {name}`text` in MyST,
and the role set is the same in both.
ubCode renders every role on this page in the editor preview and in its html and pdf builds;
a role it does not recognise is shown as a chip carrying the role’s name and its text.
The roles that point somewhere else — :ref:, :doc:, :term:, :any:, :download:
and the references into other projects — are on References and links.
Text styling roles¶
These roles format their text.
Several have a short alias:
:sub: for :subscript:, :sup: for :superscript:,
:t: and :title: for :title-reference:,
:ab: for :abbreviation: and :ac: for :acronym:.
Text styling roles
:emphasis:`Emphasis`, :strong:`strong`, :literal:`literal` and :code:`code`;
H\ :sub:`2`\ O and E = mc\ :sup:`2`;
:title-reference:`The Book of Roles`,
:abbreviation:`approx.` and :acronym:`NASA`.
Emphasis, strong, literal and code;
H2O and E = mc2;
The Book of Roles,
approx. and NASA.
{emphasis}`Emphasis`, {strong}`strong`, {literal}`literal` and {code}`code`;
H{sub}`2`O and E = mc{sup}`2`;
{title-reference}`The Book of Roles`,
{abbreviation}`approx.` and {acronym}`NASA`.
The MyST form renders live in the MyST text styling roles. A MyST role needs no backslash-space to start inside a word.
A role’s text is not parsed again for inline markup,
so *stars* inside :strong: are printed as written.
:title-reference: marks the title of a work,
and is the role of text in bare single backticks unless the default role is changed
(see The default role and custom roles).
Math¶
The :math: role typesets an inline LaTeX formula (KaTeX),
in both the preview and a built site.
Its live specimen is with the math directive, in Inline math.
UI and file roles¶
These Sphinx roles mark up what a reader types, clicks or reads on a screen.
Keys, labels and menus
Press :kbd:`Ctrl+S`, or choose :menuselection:`File --> Save As...`
and click :guilabel:`&Save`.
Press Ctrl+S, or choose and click Save.
Press {kbd}`Ctrl+S`, or choose {menuselection}`File --> Save As...`
and click {guilabel}`&Save`.
The MyST form renders live in the MyST keys, labels and menus.
:kbd:One keycap per key: a combination is split on
-,+,^or a space (ubc build pdfsets the whole combination as one key).:menuselection:A menu path, with
-->between its items drawn as a triangle.:guilabel:A label of the user interface; an
&before a letter marks that letter as its access key.
Files, commands and terms
Edit :file:`~/.config/{project}/ubproject.toml`,
then run :samp:`ubc build {builder}`.
The :command:`ubc` command, or :program:`ubc`, reads :makevar:`PATH`.
A :dfn:`specimen` shows its source and its result;
this page is :mimetype:`text/html`,
a label here matches :regexp:`^ex-roles-[a-z]+$`,
and a stack is :abbr:`LIFO (last in, first out)`.
See :manpage:`ls(1)`, the :mailheader:`Content-Type` header
and :newsgroup:`comp.lang.python`.
Edit ~/.config/project/ubproject.toml,
then run ubc build builder.
The ubc command, or ubc, reads PATH.
A specimen shows its source and its result;
this page is text/html,
a label here matches ^ex-roles-[a-z]+$,
and a stack is LIFO.
See ls(1), the Content-Type header
and comp.lang.python.
Edit {file}`~/.config/{project}/ubproject.toml`,
then run {samp}`ubc build {builder}`.
The {command}`ubc` command, or {program}`ubc`, reads {makevar}`PATH`.
A {dfn}`specimen` shows its source and its result;
this page is {mimetype}`text/html`,
a label here matches {regexp}`^ex-roles-[a-z]+$`,
and a stack is {abbr}`LIFO (last in, first out)`.
See {manpage}`ls(1)`, the {mailheader}`Content-Type` header
and {newsgroup}`comp.lang.python`.
The MyST form renders live in the MyST files, commands and terms.
:file:,:samp:Literal text in which a
{placeholder}is emphasised.:command:,:program:,:makevar:A name in bold.
:dfn:,:mimetype:,:manpage:,:mailheader:,:newsgroup:A term in italics.
:regexp:A regular expression in monospace.
:abbr:An abbreviation; a trailing
(expansion)becomes its hover text.
Note
ubc build pdf prints an :abbr: expansion in parentheses after the abbreviation.
How :kbd: and :manpage: differ from a Sphinx build is in
the inline-role differences.
PEP and RFC links¶
:pep: links to a Python Enhancement Proposal on peps.python.org, shown as PEP <number>,
and :rfc: to a Request for Comments on the IETF site, shown as RFC <number>.
Neither needs the network to build.
See {pep}`8` for style, and {rfc}`2822` for the message format.
The MyST form renders live in the MyST PEP and RFC links.
:rfc:`2822#section-3` links to a section of the RFC.
A number that is not valid — not a number, or out of range — is shown as a chip and reported
(a Sphinx build reports only a value that is not a number, and links an out-of-range one).
How the links differ from a Sphinx build is in
the inline-role differences.
Project link shorthands (extlinks)¶
An extlink role turns a repetitive URL pattern into a short role of your own,
:issue:`42` instead of the full issue-tracker URL every time.
The role names are defined by your project:
ubCode implements Sphinx’s
sphinx.ext.extlinks
extension natively,
so enable it and declare one role per [parse.extlinks] entry
in your parsing configuration:
[parse]
extensions = ["sphinx.ext.extlinks"]
[parse.extlinks.issue]
url = "https://github.com/useblocks/ubcode/issues/%s"
caption = "issue %s"
The url is a template in which %s is replaced by the role’s text;
the optional caption templates the link text the same way.
This site defines ubc-download-non-win that way, for its download links,
with the URL itself as the caption:
An extlink role
Download :ubc-download-non-win:`linux-x64`,
or :ubc-download-non-win:`the macOS build <darwin-arm64>`.
Download {ubc-download-non-win}`linux-x64`,
or {ubc-download-non-win}`the macOS build <darwin-arm64>`.
The MyST form renders live in the MyST extlink role.
Without a
caption, the link text is the expanded URL itself.The form with a title,
:issue:`the tracker <100>`, uses your title as the link text (the caption is not applied), and its target fills the%s.The text is substituted into the URL as written, not URL-encoded, so a target containing spaces produces a URL containing spaces.
An extlink is a direct external link, like :pep: and :rfc::
it renders at once, without waiting for the project index.
(A Sphinx build also tags each link with a CSS class named after the role,
extlink-issue; ubCode does not.)
While the extension is not enabled, the configured names are unknown roles,
each shown as a chip, and a [parse.extlinks] table on its own changes nothing.
A template with more than one %s (write a literal percent as %%),
or a role name that would shadow a built-in role such as ref or pep,
is reported as a configuration warning and that role is skipped;
see Parsing for the details.
Badges¶
sphinx-design’s badge roles draw a short label as a coloured pill.
A role is named bdg- and a colour
(primary, secondary, success, info, warning, danger,
light, muted, dark, white or black),
with -line for an outlined badge;
a bdg-ref- or bdg-link- role makes the badge a link,
taking the target of :ref: or a URL.
Badges
:bdg-primary:`primary`, :bdg-info-line:`outlined`,
and :bdg-ref-success:`a link to this page <authoring:roles>`.
primary, outlined, and a link to this page.
{bdg-primary}`primary`, {bdg-info-line}`outlined`,
and {bdg-ref-success}`a link to this page <authoring:roles>`.
The MyST form renders live in the MyST badges.
The default role and custom roles¶
Text in bare single backticks, with no role named, takes the default role,
which is :title-reference: unless you change it:
the .. default-role:: directive changes it from that point of the page on,
and the default_role key of the parsing configuration
sets it for every page
(see The default role).
The .. role:: directive defines a custom role, from that point of the page on.
A plain custom role renders its text in a span whose CSS class is the role’s name,
for a stylesheet to style.
A custom role
.. role:: ex-roles-flag
A :ex-roles-flag:`flagged` word carries the class ``ex-roles-flag``.
A flagged word carries the class ex-roles-flag.
```{role} ex-roles-myst-flag
```
A {ex-roles-myst-flag}`flagged` word carries the class `ex-roles-myst-flag`.
The MyST form renders live in the MyST custom role.
A derived role, written .. role:: name(base), behaves as its base role does.
Roles from an extension ubCode does not know can be declared with extend_roles
in the parsing configuration.
Highlighted inline code¶
A role derived from :code: can carry a :language: option,
and its text is then highlighted as code of that language —
the inline twin of the code-block directive.
Highlighted inline code
.. role:: ex-roles-python(code)
:language: python
In Python, :ex-roles-python:`len("abc") + 2` is :ex-roles-python:`5`.
In Python, len("abc") + 2 is 5.
```{role} ex-roles-myst-python(code)
:language: python
```
In Python, {ex-roles-myst-python}`len("abc") + 2`
is {ex-roles-myst-python}`5`.
The MyST form renders live in the MyST highlighted inline code.
The language names are the ones code blocks accept,
and a language ubCode does not recognise is shown as plain inline code.
A chain of derived roles takes the language of the nearest definition that sets one.
The plain :code: role, and a derived role with no :language:, render like :literal::
the role’s name is never used as the language.
How highlighted inline code differs from a Sphinx build is in
the code-block differences.
The variant role¶
:variant: resolves a dotted path into your configured variant data
and shows the resolved value as plain text.
Because it belongs with the other variant-authoring constructs,
its full entry lives on its own page:
see Variants.
See also
References and links — the cross-reference roles, footnotes, citations and substitutions.
Needs — needs, need IDs, and the need roles.
Differences from a Sphinx build — how ubCode differs from a Sphinx build.
Parsing — the
[parse]configuration, includingdefault_role,extend_rolesfor custom roles from your extensions, and the[parse.extlinks]link-shorthand table.