CODEWITHSUNDEEP
python-sphinxrestructuredtextread-the-docs
user2288008
user2288008

Reputation:

Insert clickable SVG image into Sphinx documentation

I have SVG image file with several nodes each is associated with URL. If I open this file directly in browser I can click on each node and it will open different URLs. However when I use this picture in my Sphinx documentation it doesn't work - picture rendered as a whole so I need to open it by View Image and only then I can click on nodes.

I'm using standard image directive:

.. image:: myfile.svg

Probably I need to use something else?

Upvotes: 17

Views: 14021

Answers (6)

Carson
Carson

Reputation: 8098

I like this way

.. raw:: html

    <a href="https://www.google.com/">
        <img src="https://img.shields.io/static/v1?&style=plastic&logo=appveyor&label=Google&message=link2google&color=FF0000" alt="No message"/></a>

demo

What's the difference between <img> and <image>?

  • <img>: standard HTML element

    The tag is a standard HTML element used to embed images into web pages.

    It supports various attributes such as src (to specify the image source), alt (alternative text for the image), width, and height.

    It's widely supported across all web browsers and is the correct way to display images in HTML documents.

  • <image> reST syntax

    The is part of the reStructuredText (reST) syntax, which is a markup language used primarily in Python documentation.

    In reStructuredText, the directive .. image:: is used to include images in the document.

  • svg element: <image>: The HTML spec defines as a synonym for while parsing HTML. This specific element and its behavior only apply inside SVG documents or inline SVGs.

Since I used ..raw:: html, it's probably better to stick to standard HTML for writing.

If you don't see any difference in the browser, it might be because the browser is trying to guess what the tags are.

Upvotes: 2

SimonBiggs
SimonBiggs

Reputation: 934

To include clickable svg links within sphinx I did the following:

.. raw:: html
    :file: ../graphs/pymedphys_analysis.gamma.svg

See:

https://raw.githubusercontent.com/pymedphys/pymedphys/1915b9496e93782bdac7dcebff7e26e470e5ff57/docs/graphs/graphs.rst

This then freed me to write the following within an imported style sheet:

svg {
    width: 100%;
}

https://github.com/pymedphys/pymedphys/blob/f4d404fa1cf3f551c4aa80ef27438f418c61a436/docs/_static/style.css

This made the svg fit the container as desired.

See:

https://pymedphys.com/developer/dependencies.html#pymedphys

Upvotes: 3

winni2k
winni2k

Reputation: 1515

I am probably misunderstanding the OP's requirements, but why not just include the SVG into the sphinx documentation as html? This appears to work for me:

.. raw:: html
    :file: images/image.svg

Upvotes: 5

bluprince13
bluprince13

Reputation: 5001

I'm still looking for a better solution myself, but I ran into the same problem and used this workaround.

You can use the download directive to give the user a link to the file.

:download:`svg <images/image.svg>`

Upvotes: 1

mb21
mb21

Reputation: 39488

Sphinx generates <img> tags for images, which makes sense in most cases. However, to have the links inside the svg be clickable, you should use an <object> tag, i.e.:

.. raw:: html

    <object data="myfile.svg" type="image/svg+xml"></object>

(Regarding the GitHub issue you linked to, I don't think there's a lot that Sphinx can do here—it's really quite complicated—short of introducing a new option to the .. image directive that lets the user specify whether to render as an img or object tag.)

Upvotes: 17

N&#230;reen
N&#230;reen

Reputation: 1206

One simple solution would be to add a link to the svg file in this .. image:: myfile.svg command:

.. image:: myfile.svg
   :target: _images/myfile.svg

Take care of checking the relative directory where the images are copied when the html files are generated. By default, it should be _images/.

This way, you can click the SVG file, to see it in a plain page, and then click on it as usual (not a perfect solution but still..).

Upvotes: 8

Related Questions