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.
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 links’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.
For the Python object roles, if you prefix the content with ~, the link text will only be the last component of the target. For example, :meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text.
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.
The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found:
The name of an object of unspecified type. Useful e.g. as the default_role.
New in version 0.4.
The name enclosed in this markup can include a module name and/or a class name. For example, :func:`filter` could refer to a function named filter in the current module, or the built-in function of that name. In contrast, :func:`foo.filter` clearly refers to the filter function in the foo module.
Normally, names in these roles are searched first without any further qualification, then with the current module name prepended, then with the current module and class name (if any) prepended. If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python’s codecs module, :func:`open` always refers to the built-in function, while :func:`.open` refers to codecs.open().
A similar heuristic is used to determine whether the name is an attribute of the currently documented class.
The following roles create cross-references to C-language constructs if they are defined in the documentation:
The following roles do possibly create a cross-reference, but do not refer to objects:
The following role creates a cross-reference to the term in the glossary:
Reference to a term in the glossary. The 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.
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`. 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: given
.. _my-figure:
.. figure:: whatever
Figure caption
a reference :ref:`my-figure` would insert a reference to the figure with link text “Figure caption”.
Labels that aren’t placed before a section title can still be referenced to, but you must give the link an explicit title, using this syntax: :ref:`Link title <label-name>`.
Using ref is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, and for all builders that support cross-references.
New in version 0.6.
There is also a way to directly link to documents:
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.
New in version 0.6.
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.
The following roles don’t do anything special except formatting the text in a different style:
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.
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.
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.
A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part, as in :file:.
If you don’t need the “variable part” indication, use the standard ``code`` instead.
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.
The documentation system provides three substitutions that are defined by default. They are set in the build configuration file.