References¶

Cross-references¶

To cross-reference to arbitrary locations within one document, use the ref role. Reference target names need to start with an underscore. For example, .. _example:. However, the reference itself should not have the underscore preceding the reference. For example, example. For more information on referencing, see Internal Hyperlink Targets.

Input

.. _cg_titles:

Titles
~~~~~~

This is the section we want to reference to.

...

The following - :ref:`cg_titles` - generates a link to the section with
the defined label using this section heading as a link title.

A link label and a reference can be defined in separate source files,
but within one directory. Otherwise, use the external linking.

Output

…

The following - Titles - generates a link to the section with the defined label using this section heading as a link title.

A link label and a reference can be defined in separate source files, but within one directory. Otherwise, use the external linking.

Reference works only if it points to heading or section. For making link to any location you must give your reference an explicit title, using this syntax: :ref:`Link title <label-name>`.

Input

.. _label used in referencing file:

**Input**

This is the section we want to reference to.

...

Here is a link to :ref:`that label located in another file
<label used in referencing file>`.

Output

Here is a link to that label located in another file.

External references¶

To link to some external locations, format the RST source as follows:

Do not apply any markups to specify a web link.
If you need a specific link title to appear in the output, format a web link as Link text <http://web-link.com> wrapping it in backticks.
Do not separate the link name from the link itself by defining the link in another place in your document. It prevents translated documents from using different links, for example, corresponding links to translated versions.

Input

 Here is a link to the Linux Foundation home page: https://www.linuxfoundation.org.

 Here is an external web link with a link title:
`Linux Foundation <https://www.linuxfoundation.org>`_.

Output

Here is a link to the Linux Foundation home page: https://www.linuxfoundation.org.

Here is an external web link with a link title: Linux Foundation.

Links¶

In some cases same locations might be mentioned many times in the same document. Instead of embeding URI inline each time use links. All hyperlink target should be put at the end of the file.

Input

Here is a link to `Signed CLAs wiki page`_.
And here is another paragraph with a link to the same `Signed CLAs wiki page`_.

.. _Signed CLAs wiki page: https://wiki.tungsten.io/display/TUN/Signed+CLAs

Output

Here is a link to Signed CLAs wiki page. And here is another paragraph with a link to the same Signed CLAs wiki page.

This documentation, is a derivative of RST conventions by OpenStack, used under CC BY.