diff options
Diffstat (limited to 'doc/usage/referencing.rst')
| -rw-r--r-- | doc/usage/referencing.rst | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst new file mode 100644 index 0000000..c2ad715 --- /dev/null +++ b/doc/usage/referencing.rst @@ -0,0 +1,258 @@ +.. _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:`.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 :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```. 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 + :dudir:`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 :rst:role:`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 +--------------------------- + +.. 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 a ``_downloads/<unique hash>/`` + 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 +------------------------------------------ + +.. versionadded:: 1.3 + +.. versionchanged:: 1.5 + :rst:role:`numref` role can also refer sections. + And :rst:role:`numref` allows ``{name}`` for the link text. + +.. rst:role:: 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 :confval:`numfig_format` setting is + used as fall-back default. + + If :confval:`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: + +.. 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. This generates a link to + a :rst:dir:`option` directive, if it exists. + + +The following role creates a cross-reference to a term in a +:ref:`glossary <glossary-directive>`: + +.. rst:role:: 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. |