Links and references
To create a link to another document in our documentation, we use the :doc:
role.
For example, this link points to the document /reference/reference_lua/box_error.rst
:
:doc:`box.error reference </reference/reference_lua/box_error>`
Our convention is to put the full path to the referred document so that we can
easily replace the path if it changes.
Note that we can omit the .rst
part of the filename.
You can use the target document’s title as the link text. To do so, omit the text in the link definition:
:doc:`/reference/reference_lua/box_index`
And you will get this:
To generate a link to the certain place in the page, we use the :ref:
role.
For this purpose, we add our own labels for linking to any place in this documentation.
Соглашение об именовании заключается в следующем:
- Character set: a through z, 0 through 9, hyphen, underscore.
- Format:
path hyphen filename hyphen tag
Пример:
.. _c_api-box_index-iterator_type:
где:
c_api
is the directory name,box_index
is the file name (without «.rst»), anditerator_type
is the tag.
Use a hyphen «-» to delimit the path and the file name. In the documentation source, we use only underscores «_» in paths and file names, reserving the hyphen «-» as the delimiter for local links.
The tag can be anything meaningful. The only guideline is for Tarantool syntax
items (such as members), where the preferred tag syntax is
module_or_object_name hyphen member_name
. For example, box_space-drop
.
To add a link to an anchor, use the following syntax:
Check out the :ref:`Quick start guide <vshard-quick-start>`.
The result will be like this:
Check out the Quick start guide.
To make an external link, use the following syntax:
Feel free to report an issue at `Tarantool GitHub <https://github.com/tarantool/tarantool/issues>`_.
Избегайте разделения ссылки и определения цели, например:
Feel free to report an issue at `Tarantool GitHub`_. .. _Tarantool GitHub: https://github.com/tarantool/tarantool/issues
because every separated link tends to cause troubles when this documentation is translated to other languages.