Search code examples
htmlimagepython-sphinxrestructuredtext

Use image in Sphinx as clickable link

Problem:

I have a table of images that I'm using as an overview/introduction. I want the end-user to be able to click on the image and it link to the HTML page for that image's corresponding introductory information1.

The problem is I can't seem to get the linking part to work. The table of images shows up fine, but clicking on an image just takes me to a page not found screen (see image at bottom of post). I've spent about an hour on Google but haven't found a solution yet.




1each image has a corresponding .rst file with the info I want the end-user to see

Info:

  • Sphinx 1.8.5
  • Python 3.7.6 (MiniConda)
  • Building html pages from reStructuredText files
    • sphinx-build -b html source build
    • make clean html
    • make html
  • Nothing special has been done in my conf.py file, other than including the RTD theme
    • I'm guessing I will need to do something fancy in my conf.py file if doing what I want is possible at all
  • Adding the .rst files to the .. toc:: directive in introduction_file.rst didn't help

Here is the reST code I have so far:

  • the image directives are all inside a table; table omitted for brevity
  • I'm also confident that the 'image directives inside a table' thing is not the issue
    .. filename is "introduction_file.rst"
    
    .. image:: images/my_first_image.png
       :scale: 100%
       :alt: My First PNG Image
       :align: center
       :target: introduction_files/my_first_image_intro_file.rst

    .. also didn't work:
    .. :target: introduction_files/my_first_image_intro_file.html

File Structure:

  • Home.rst is the entry point for the HTML pages (i.e. it used to be called index.rst until I renamed it and refactored conf.py accordingly)
--build
    ...
-- source
   |--Introduction/
      |--introduction_file.rst
      |--images/
         |--my_first_image.png
         |--my_second_image.png
             ...
      |--introduction_files/
         |--my_first_image_intro_file.rst
         |--my_second_image_intro_file.rst
             ...
   |--_static/
       ...
   |--_templates/
       ...
   |--conf.py
   |--Home.rst

I'm not opposed to doing what I want in HTML/CSS, but if there is a way to do it in sphinx then I'd prefer to do it that way. I will end up editing the HTML code regardless, but the less editing the better; Sphinx is essentially a quick-start or template.

This image is what I see in my browser when I click on one of the images in my table-of-images. The URL bar in Chrome shows the correct path to the .rst file though, so I'm a bit confused.

  • I tried changing the :target: file extension to .html but that didn't work either

Result of clicking on the images

Edit: forgot to add the location of introduction_file.rst to the folder structure

Solution:

Mix up between the paths. I was linking to the file in the source directory, but needed to link to the file in the build directory. Had to navigate back to the root directory with a few '../' prefixes, then navigate to the .html information file in the build directory. In other words, this is what it ended up looking like:

    .. filename is "introduction_file.rst"
    
    .. image:: images/my_first_image.png
       :scale: 100%
       :alt: My First PNG Image
       :align: center
       :target: ../../../build/html/Introduction/introduction_files/my_first_image_intro_file.html
Solution

  • The target option's value must be either relative to introduction_file.rst (you don't provide its location so you'll have to figure that out), or absolute to the documentation root, i.e., /Introduction/introduction_files/my_first_image_intro_file.html.