Skip to content

Latest commit

 

History

History
501 lines (326 loc) · 16.9 KB

roles.rst

File metadata and controls

501 lines (326 loc) · 16.9 KB
Raw

rst

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 :confval:`default_role config value to set it to a known role -- the :rstany role to find anything or the :rstpy:obj role to find Python objects are very useful for this.

See /usage/restructuredtext/domains for roles added by domains.

Cross-referencing syntax

Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write :role:`target`, and a link will be created to the item named target of the type indicated by role. The link's text will be the same as target.

There are some additional facilities, however, that make cross-referencing roles more versatile:

  • You may supply an explicit title and reference target, like in reST direct hyperlinks: :role:`title <target>` will refer to target, but the link text will be title.
  • If you prefix the content with !, no reference/hyperlink will be created.

  • If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get will refer to Queue.Queue.get but only display get` as the link text. This does not work with all cross-reference roles, but is domain specific.

    In HTML output, the link's title attribute (that is e.g. shown as a tool-tip on mouse-hover) will always be the full target name.

Cross-referencing anything

Cross-referencing objects

These roles are described with their respective domains:

  • Python <python-roles>
  • C <c-roles>
  • C++ <cpp-roles>
  • JavaScript <js-roles>
  • ReST <rst-roles>

Cross-referencing arbitrary locations

Cross-referencing documents

0.6

There is also a way to directly link to documents:

Referencing downloadable files

0.6

Cross-referencing figures by figure number

1.3

1.5 numref role can also refer sections. And numref allows {name} for the link text.

Cross-referencing other items of interest

The following roles do possibly create a cross-reference, but do not refer to objects:

The following role creates a cross-reference to a term in a glossary <glossary-directive>:

Inline code highlighting

Math

Other semantic markup

The following roles don't do anything special except formatting the text in a different style:

Is this not part of the standard domain?

There is also an :rstindex role to generate index entries.

The following roles generate external links:

Note that there are no special roles for including hyperlinks as you can use the standard reST markup for that purpose.

Substitutions

The documentation system provides three substitutions that are defined by default. They are set in the build configuration file.

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 by release.

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 by version.

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 by today_fmt and today.