python-sphinxcross-reference

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


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 ?


Solution

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

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

    The label is enclosed in literal angle brackets.

    See https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref.