Roles¶
Sphinx uses interpreted text roles to insert semantic markup into documents.
They are written as :rolename:`content`
.
Note
The default role (`content`
) has no special meaning by default. You are
free to use it for anything you like, e.g. variable names; use the
default_role
config value to set it to a known role – the
any
role to find anything or the py:obj
role to find
Python objects are very useful for this.
See Domains for roles added by domains.
Cross-references¶
See Cross-references.
Cross-reference roles include:
Inline code highlighting¶
- :code:¶
An inline code example. When used directly, this role just displays the text without syntax highlighting, as a literal.
By default, inline code such as :code:`1 + 2` just displays without highlighting.
Displays: By default, inline code such as
1 + 2
just displays without highlighting.Unlike the
code-block
directive, this role does not respect the default language set by thehighlight
directive.To enable syntax highlighting, you must first use the Docutils role directive to define a custom role associated with a specific language:
.. role:: python(code) :language: python In Python, :python:`1 + 2` is equal to :python:`3`.
To display a multi-line code example, use the
code-block
directive instead.
Math¶
- :math:¶
Role for inline math. Use like this:
Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
Displays: Since Pythagoras, we know that \(a^2 + b^2 = c^2\).
- :eq:¶
Same as
math:numref
.
Other semantic markup¶
The following roles don’t do anything special except formatting the text in a different style:
- :abbr:¶
An abbreviation. If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML, and output only once in LaTeX.
For example:
:abbr:`LIFO (last-in, first-out)`
displays LIFO.Added in version 0.6.
- :command:¶
The name of an OS-level command, such as
rm
.For example: rm
- :dfn:¶
Mark the defining instance of a term in the text. (No index entries are generated.)
For example: binary mode
- :file:¶
The name of a file or directory. Within the contents, you can use curly braces to indicate a “variable” part, for example:
... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...
Displays: … is installed in
/usr/lib/python3.x/site-packages
…In the built documentation, the
x
will be displayed differently to indicate that it is to be replaced by the Python minor version.
- :guilabel:¶
Labels presented as part of an interactive user interface should be marked using
guilabel
. This includes labels from text-based interfaces such as those created usingcurses
or other text-based libraries. Any label used in the interface should be marked with this role, including button labels, window titles, field names, menu and menu selection names, and even values in selection lists.Changed in version 1.0: An accelerator key for the GUI label can be included using an ampersand; this will be stripped and displayed underlined in the output (for example:
:guilabel:`&Cancel`
displays Cancel). To include a literal ampersand, double it.
- :kbd:¶
Mark a sequence of keystrokes. What form the key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an xemacs key sequence may be marked like
:kbd:`C-x C-f`
, but without reference to a specific application or platform, the same sequence should be marked as:kbd:`Control-x Control-f`
, displaying C-x C-f and Control-x Control-f respectively.
- :mailheader:¶
The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same “style.” This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. For example:
:mailheader:`Content-Type`
displays Content-Type.
- :makevar:¶
The name of a make variable.
For example: help
- :manpage:¶
A reference to a Unix manual page including the section, e.g.
:manpage:`ls(1)`
displays ls(1). Creates a hyperlink to an external site rendering the manpage ifmanpages_url
is defined.Changed in version 7.3: Allow specifying a target with
<>
, like hyperlinks. For example,:manpage:`blah <ls(1)>`
displays blah.
Menu selections should be marked using the
menuselection
role. This is used to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence. The names of individual selections should be separated by-->
.For example, to mark the selection “Start > Programs”, use this markup:
:menuselection:`Start --> Programs`
Displays:
When including a selection that includes some trailing indicator, such as the ellipsis some operating systems use to indicate that the command opens a dialog, the indicator should be omitted from the selection name.
menuselection
also supports ampersand accelerators just likeguilabel
.
- :mimetype:¶
The name of a MIME type, or a component of a MIME type (the major or minor portion, taken alone).
For example: text/plain
- :newsgroup:¶
The name of a Usenet newsgroup.
For example: comp.lang.python
- :program:¶
The name of an executable program. This may differ from the file name for the executable for some platforms. In particular, the
.exe
(or other) extension should be omitted for Windows programs.For example: curl
- :regexp:¶
A regular expression. Quotes should not be included.
For example:
([abc])+
- :samp:¶
A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part, as in
file
. For example, in:samp:`print(1+{variable})`
, the partvariable
would be emphasized:print(1+variable)
If you don’t need the “variable part” indication, use the standard
code
role instead.Changed in version 1.8: Allowed to escape curly braces with double backslash. For example, in
:samp:`print(f"answer=\\{1+{variable}*2\\}")`
, the partvariable
would be emphasized and the escaped curly braces would be displayed:print(f"answer={1+variable*2}")
There is also an index
role to generate index entries.
The following roles generate external links:
- :cve:¶
A reference to a Common Vulnerabilities and Exposures record. This generates appropriate index entries. The text “CVE number“ is generated; with a link to an online copy of the specified CVE. You can link to a specific section by using
:cve:`number#anchor`
.For example: CVE 2020-10735
Added in version 8.1.
- :cwe:¶
A reference to a Common Weakness Enumeration. This generates appropriate index entries. The text “CWE number“ is generated; in the HTML output, with a link to an online copy of the specified CWE. You can link to a specific section by using
:cwe:`number#anchor`
.For example: CWE 787
Added in version 8.1.
- :pep:¶
A reference to a Python Enhancement Proposal. This generates appropriate index entries. The text “PEP number“ is generated; in the HTML output, this text is a hyperlink to an online copy of the specified PEP. You can link to a specific section by saying
:pep:`number#anchor`
.For example: PEP 8
- :rfc:¶
A reference to an Internet Request for Comments. This generates appropriate index entries. The text “RFC number“ is generated; in the HTML output, this text is a hyperlink to an online copy of the specified RFC. You can link to a specific section by saying
:rfc:`number#anchor`
.For example: RFC 2324
Note that there are no special roles for including hyperlinks as you can use the standard reStructuredText markup for that purpose.
Substitutions¶
The documentation system provides some substitutions that are defined by default. They are set in the build configuration file.
- |release|
Replaced by the project release the documentation refers to. This is meant to be the full version string including alpha/beta/release candidate tags, e.g.
2.5.2b3
. Set byrelease
.
- |version|
Replaced by the project version the documentation refers to. This is meant to consist only of the major and minor version parts, e.g.
2.5
, even for version 2.5.1. Set byversion
.
- |today|
Replaced by either today’s date (the date on which the document is read), or the date set in the build configuration file. Normally has the format
April 14, 2007
. Set bytoday_fmt
andtoday
.
- |translation progress|
Replaced by the translation progress of the document. This substitution is intended for use by document translators as a marker for the translation progress of the document.