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-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
--------------------------

:any:

   New in version 1.3.

   This convenience role tries to do its best to find a valid target
   for its reference text.

   * First, it tries standard cross-reference targets that would be
     referenced by "doc", "ref" or "option".

     Custom objects added to the standard domain by extensions (see
     "Sphinx.add_object_type()") are also searched.

   * Then, it looks for objects (targets) in all loaded domains.  It
     is up to the domains how specific a match must be.  For example,
     in the Python domain a reference of ":any:`Builder`" would match
     the "sphinx.builders.Builder" class.

   If none or multiple targets are found, a warning will be emitted.
   In the case of multiple targets, you can change "any" to a specific
   role.

   This role is a good candidate for setting "default_role".  If you
   do, you can write cross-references without a lot of markup
   overhead.  For example, in this Python function documentation

      .. function:: install()

         This function installs a `handler` for every signal known by the
         `signal` module.  See the section `about-signals` for more information.

   there could be references to a glossary term (usually
   ":term:`handler`"), a Python module (usually ":py:mod:`signal`" or
   ":mod:`signal`") and a section (usually ":ref:`about-signals`").

   The "any" role also works together with the "intersphinx"
   extension: when no local cross-reference is found, all object types
   of intersphinx inventories are also searched.


Cross-referencing objects
-------------------------

These roles are described with their respective domains:

* Python

* C

* C++

* JavaScript

* ReST


Cross-referencing arbitrary locations
-------------------------------------

:ref:

   To support cross-referencing to arbitrary locations in any
   document, the standard reST labels are used.  For this to work
   label names must be unique throughout the entire documentation.
   There are two ways in which you can refer to labels:

   * If you place a label directly before a section title, you can
     reference to it with ":ref:`label-name`".  For example:

        .. _my-reference-label:

        Section to cross-reference
        --------------------------

        This is the text of the section.

        It refers to the section itself, see :ref:`my-reference-label`.

     The ":ref:" role would then generate a link to the section, with
     the link title being "Section to cross-reference".  This works
     just as well when section and reference are in different source
     files.

     Automatic labels also work with figures. For example:

        .. _my-figure:

        .. figure:: whatever

           Figure caption

     In this case, a  reference ":ref:`my-figure`" would insert a
     reference to the figure with link text "Figure caption".

     The same works for tables that are given an explicit caption
     using the table directive.

   * Labels that aren't placed before a section title can still be
     referenced, but you must give the link an explicit title, using
     this syntax: ":ref:`Link title <label-name>`".

   Note:

     Reference labels must start with an underscore. When referencing
     a label, the underscore must be omitted (see examples above).

   Using "ref" is advised over standard reStructuredText links to
   sections (like "`Section title`_") because it works across files,
   when section headings are changed, will raise warnings if
   incorrect, and works for all builders that support cross-
   references.


Cross-referencing documents
---------------------------

New in version 0.6.

There is also a way to directly link to documents:

:doc:

   Link to the specified document; the document name can be specified
   in absolute or relative fashion.  For example, if the reference
   ":doc:`parrot`" occurs in the document "sketches/index", then the
   link refers to "sketches/parrot".  If the reference is
   ":doc:`/people`" or ":doc:`../people`", the link refers to
   "people".

   If no explicit link text is given (like usual: ":doc:`Monty Python
   members </people>`"), the link caption will be the title of the
   given document.


Referencing downloadable files
------------------------------

New in version 0.6.

:download:

   This role lets you link to files within your source tree that are
   not reST documents that can be viewed, but files that can be
   downloaded.

   When you use this role, the referenced file is automatically marked
   for inclusion in the output when building (obviously, for HTML
   output only). All downloadable files are put into the "_downloads"
   subdirectory of the output directory; duplicate filenames are
   handled.

   An example:

      See :download:`this example script <../example.py>`.

   The given filename is usually relative to the directory the current
   source file is contained in, but if it absolute (starting with
   "/"), it is taken as relative to the top source directory.

   The "example.py" file will be copied to the output directory, and a
   suitable link generated to it.

   Not to show unavailable download links, you should wrap whole
   paragraphs that have this role:

      .. only:: builder_html

         See :download:`this example script <../example.py>`.


Cross-referencing figures by figure number
------------------------------------------

New in version 1.3.

Changed in version 1.5: *numref* role can also refer sections. And
*numref* allows *{name}* for the link text.

:numref:

   Link to the specified figures, tables, code-blocks and sections;
   the standard reST labels are used.  When you use this role, it will
   insert a reference to the figure with link text by its figure
   number like "Fig. 1.1".

   If an explicit link text is given (as usual: ":numref:`Image of
   Sphinx (Fig. %s) <my-figure>`"), the link caption will serve as
   title of the reference. As placeholders, *%s* and *{number}* get
   replaced by the figure number and  *{name}* by the figure caption.
   If no explicit link text is given, the "numfig_format" setting is
   used as fall-back default.

   If "numfig" is "False", figures are not numbered, so this role
   inserts not a reference but the label or the link text.


Cross-referencing other items of interest
-----------------------------------------

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

:envvar:

   An environment variable.  Index entries are generated.  Also
   generates a link to the matching "envvar" directive, if it exists.

:token:

   The name of a grammar token (used to create links between
   "productionlist" directives).

:keyword:

   The name of a keyword in Python.  This creates a link to a
   reference label with that name, if it exists.

:option:

   A command-line option to an executable program.  This generates a
   link to a "option" directive, if it exists.

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

:term:

   Reference to a term in a glossary.  A glossary is created using the
   "glossary" directive containing a definition list with terms and
   definitions.  It does not have to be in the same file as the "term"
   markup, for example the Python docs have one global glossary in the
   "glossary.rst" file.

   If you use a term that's not explained in a glossary, you'll get a
   warning during build.


Math
====

:math:

   Role for inline math.  Use like this:

      Since Pythagoras, we know that :math:`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.

   Example: ":abbr:`LIFO (last-in, first-out)`".

   New in version 0.6.

:command:

   The name of an OS-level command, such as "rm".

:dfn:

   Mark the defining instance of a term in the text.  (No index
   entries are generated.)

: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/python2.{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 using "curses" 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 (example: ":guilabel:`&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`".

: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`".

:makevar:

   The name of a **make** variable.

:manpage:

   A reference to a Unix manual page including the section, e.g.
   ":manpage:`ls(1)`". Creates a hyperlink to an external site
   rendering the manpage if "manpages_url" is defined.

:menuselection:

   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`

   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 like
   "guilabel".

:mimetype:

   The name of a MIME type, or a component of a MIME type (the major
   or minor portion, taken alone).

:newsgroup:

   The name of a Usenet newsgroup.

Todo: Is this not part of the standard domain?

: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.

:regexp:

   A regular expression. Quotes should not be included.

: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 part "variable"
   would be emphasized.

   If you don't need the "variable part" indication, use the standard
   "``code``" instead.

   Changed in version 1.8: Allowed to escape curly braces with
   backslash

There is also an "index" role to generate index entries.

The following roles generate external links:

: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`".

: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`".

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.

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

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

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