Sphinx & reStructuredText : how to link an image to a document page

Question

In the RST syntax, you can specify a :target: attribute for setting a link. I would like to link the image to a "materials.rst" doc page, whose main section title is "Materials"

But neither of these work as target value:

• :target: `materials`_
• :target: :doc: materials
• :target: materials

How can I achieve this?

Answer 1

Not fixed even after 6 years, although :ref: works now across files just fine. However, you can't use :ref: within image or figure directives.

try using this:

:target: materials.html

...and hope for the best! The :target: role seems to accept HTML links only.

Let's assume there is some file named doc.rst which I want to access via the thumbnail in another document:

.. _doc:

Some Title
==========

...and then, in another document, I use the following solutions:

.. image:: /media/thumbnail_of_my_doc.jpg
   :ref:`doc` <- doesn't compute
   :target: doc (or doc.rst, or doc_) <- doesn't work either
   :target: doc.html <- works im my case

The last option works just because I assumed the name of the HTML to be generated. What if I was wrong? This is a pure hack. I can't believe no one got bothered to fix this.

I use RTD theme on Sphinx 4.2.0. all is updated to the newest versions.