blob: b5bb8d0c5449a558a1f68bc3155b3228ed133ef5 [file] [log] [blame]
.. highlight:: rest
.. _inline-markup:
Inline markup
=============
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
:rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find
Python objects are very useful for this.
See :ref:`domains` for roles added by domains.
.. _xref-syntax:
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.
.. _any-role:
Cross-referencing anything
--------------------------
.. rst:role:: any
.. versionadded:: 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 :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`.
Custom objects added to the standard domain by extensions (see
:meth:`.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 :confval:`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 :rst:role:`any` role also works together with the
:mod:`~sphinx.ext.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:
* :ref:`Python <python-roles>`
* :ref:`C <c-roles>`
* :ref:`C++ <cpp-roles>`
* :ref:`JavaScript <js-roles>`
* :ref:`ReST <rst-roles>`
.. _ref-role:
Cross-referencing arbitrary locations
-------------------------------------
.. rst:role:: 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```. 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".
The same works for tables that are given an explicit caption using the
:dudir:`table` directive.
* 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 :rst:role:`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.
Cross-referencing documents
---------------------------
.. versionadded:: 0.6
There is also a way to directly link to documents:
.. rst:role:: 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
------------------------------
.. versionadded:: 0.6
.. rst:role:: 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.
Cross-referencing other items of interest
-----------------------------------------
The following roles do possibly create a cross-reference, but do not refer to
objects:
.. rst:role:: envvar
An environment variable. Index entries are generated. Also generates a link
to the matching :rst:dir:`envvar` directive, if it exists.
.. rst:role:: token
The name of a grammar token (used to create links between
:rst:dir:`productionlist` directives).
.. rst:role:: keyword
The name of a keyword in Python. This creates a link to a reference label
with that name, if it exists.
.. rst:role:: option
A command-line option to an executable program. The leading hyphen(s) must
be included. This generates a link to a :rst:dir:`option` directive, if it
exists.
The following role creates a cross-reference to the term in the glossary:
.. rst:role:: term
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.
Other semantic markup
~~~~~~~~~~~~~~~~~~~~~
The following roles don't do anything special except formatting the text
in a different style:
.. rst:role:: 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)```.
.. versionadded:: 0.6
.. rst:role:: command
The name of an OS-level command, such as ``rm``.
.. rst:role:: dfn
Mark the defining instance of a term in the text. (No index entries are
generated.)
.. rst:role:: 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.
.. rst:role:: 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 :mod:`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.
.. versionchanged:: 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.
.. rst:role:: 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```.
.. rst:role:: 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```.
.. rst:role:: makevar
The name of a :command:`make` variable.
.. rst:role:: manpage
A reference to a Unix manual page including the section,
e.g. ``:manpage:`ls(1)```.
.. rst:role:: 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
:rst:role:`guilabel`.
.. rst:role:: mimetype
The name of a MIME type, or a component of a MIME type (the major or minor
portion, taken alone).
.. rst:role:: newsgroup
The name of a Usenet newsgroup.
.. rst:role:: 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.
.. rst:role:: regexp
A regular expression. Quotes should not be included.
.. rst:role:: samp
A piece of literal text, such as code. Within the contents, you can use
curly braces to indicate a "variable" part, as in :rst:role:`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.
There is also an :rst:role:`index` role to generate index entries.
The following roles generate external links:
.. rst:role:: 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```.
.. rst:role:: 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.
.. _default-substitutions:
Substitutions
~~~~~~~~~~~~~
The documentation system provides three substitutions that are defined by
default. They are set in the build configuration file.
.. describe:: |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 :confval:`release`.
.. describe:: |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 :confval:`version`.
.. describe:: |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 :confval:`today_fmt` and :confval:`today`.