How to choose the text use in a cross-reference with Sphinx?

Question

Using sphinx, I included a figure using the following syntax.

.. _struct_NiO:

.. figure:: img/NiO.png
   :align: center
   :width: 400px

   long long very long caption ...

In another part of the text I used

See figure :ref:`struct_NiO` bla bla bla

in order to do a cross reference to the figure. This work, but the output looks like :

See figure "long long very long caption ..." bla bla bla.

This is the normal behavior of sphinx, but if you have a figure a little bit complicated with a 3 or 4 lines caption it is no really adapted.

Is it possible to select the text used in the cross reference ?

Answer 1

You can provide a custom link text for :ref: targets, like this:

See figure :ref:`Link text <struct_NiO>` bla bla bla

See http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role.