Links and references

Linking to other documentation pages

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:

Вложенный модуль box.index

Linking to labels (anchors)

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»), and
• iterator_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.