`:loading: embed` on images does not work as expected

[Johnnynator]

trafficstars

Describe the bug

Sphinx refers to docutils for all reST behaviour (except where it extends it), so I would expect that :loading: embed would work as documented by docutils (v0.21+).

sphinx breaks :loading: embed in two scenarios:

• docutils only gets the future _images path, so docutils can't read the image file (and not embed it) and prints an error in the output
• svg's never get passed to docutils and therefore docutils won't even try to embed them

How to Reproduce

cat << EOF > index.rst
####
Test
####

.. image:: test.svg
   :loading: embed

.. image:: test.png
   :loading: embed
EOF
cat << EOF > test.svg
<?xml version="1.0" encoding="UTF-8"?>
<svg version="1.1" width="300" height="200" xmlns="http://www.w3.org/2000/svg">
  <rect width="100%" height="100%" fill="red" />
</svg>
EOF
echo "" > conf.py
echo iVBORw0KGgoAAAANSUhEUgAAASwAAADIAQMAAABoEU4WAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURf8AAP///0EdNBEAAAABYktHRAH/Ai3eAAAAB3RJTUUH6AUDDiEChJlKFAAAAB5JREFUWMPtwTEBAAAAwqD1T20Hb6AAAAAAAAAA4DceeAABFyjdmQAAAABJRU5ErkJggg== | base64 -d > test.png
sphinx-build -M html . _build/

Environment Information

Platform:              linux; (Linux-6.7.12-amd64-x86_64-with-glibc2.37)
Python version:        3.11.9 (main, Apr 10 2024, 13:16:36) [GCC 13.2.0])
Python implementation: CPython
Sphinx version:        7.3.7
Docutils version:      0.21.1
Jinja2 version:        3.1.3
Pygments version:      2.17.2

Sphinx extensions

No response

Additional context

No response

[jayaddison]

Hi @Johnnynator - thanks for the bugreport. Let's check if I understand your request correctly:

• Docutils 0.21+ allows some image files in source rST projects to be annotated as for embedded use; this means that each relevant image file is not included in the output build as a standalone named file, but is instead replicated (perhaps using data: URIs, embedded XML, or other formatting as available based on the output format and image type) each time the image is referenced, from each output document that references it.
• You would like Sphinx to respect the same loading option flag that docutils uses for these annotations.

Could I also ask what behaviour docutils provides if-and-when writing such embedded-annotated images to a purely text-based output format?

And if possible: could you share more about the use-case(s) that you anticipate this would help with? In other words: not only the change in behaviour that you'd like, but the reasons why that could be beneficial in particular usage scenarios.

[Johnnynator]

https://docutils.sourceforge.io/docs/ref/rst/directives.html#footnote-4

Yep, base64 data uri for for most things, svg directly embedded as is into the html.

Could I also ask what behaviour docutils provides if-and-when writing such embedded-annotated images to a purely text-based output format?

The loading attribute is only used for their html writer, other writers do ignore it.

My usecase is primarly taking use of how svg's get styled differently when they are embeddes in the html document compared getting linked with e.g. . Makes it easier to have a single svg that can handle both light and dark mode.

For normal images it would be beneficial to get rid of the ugly error message in the output html.

[jayaddison]

Could I also ask what behaviour docutils provides if-and-when writing such embedded-annotated images to a purely text-based output format?

The loading attribute is only used for their html writer, other writers do ignore it.

Ok, thank you.

My usecase is primarly taking use of how svg's get styled differently when they are embeddes in the html document compared getting linked with e.g. . Makes it easier to have a single svg that can handle both light and dark mode.

I'm not sure I understand this part - what's a situation where an embedded SVG is easier to style than an SVG included by using a (non-data) img src reference?

For normal images it would be beneficial to get rid of the ugly error message in the output html.

Could you post some build logs including the error message?

[Johnnynator]

I'm not sure I understand this part - what's a situation where an embedded SVG is easier to style than an SVG included by using a (non-data) img src reference?

furo theme you can reuse the css properties of it, or at least access body[data-theme="dark"] (or light), an svg in an <img> tag can only use the dark/light media query and would break with the dark/light mode toggle of furo.

Could you post some build logs including the error message?

Build log:

Running Sphinx v7.3.7
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
/home/john/Projects/sphinx-test/doc/index.rst:7: ERROR: Cannot embed image "_images/test.png":
  [Errno 2] No such file or directory: '_images/test.png'
generating indices... genindex done
writing additional pages... search done
copying images... [100%] test.png
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in build.

Error Message on the Webpage:

System Message: ERROR/3 (/home/john/Projects/sphinx-test/doc/index.rst, line 8)

Cannot embed image "_images/test.png": [Errno 2] No such file or directory: '_images/test.png'

Screenshoot of Document (Output of "How to Reproduce")

[jayaddison]

First of all, thanks for the screenshot: when you mentioned that the error message appeared in the output in your previous messages, I misinterpreted that as being the Sphinx build logs -- I didn't realize that the error appears within the built project content itself (output is a perfectly valid way to refer to that).

The SVG styling question seems to make some sense, but it is at-or-beyond the limits of my SVG/stylesheet experience; I'll try to learn some more about that.

The docutils code to embed SVGs has a comment to indicate that it's provisional and subject to change, so it may be worth proceeding gradually with functionality here.

[jayaddison]

A small concern I had about adding support for embedded SVGs is that there is no implicit namespace for each SVG file embedded within an HTML document. This can cause collisions between the id values of separate SVG images within a document. It seems that the docutils folks are aware of this, though - it's mentioned in the relevant commit message.

[chrisjsewell]

heya yep agree that this should be in sphinx and is useful, in fact I'm just dealing with a case now of moving from <img src to embedded, to deal with theme compatibility: https://github.com/useblocks/sphinx-needs/pull/1181