image directive fails for "wild card" inclusion

[shimizukawa]

I have a document from that I want to produce a web version and a LaTeX version. I'm including images and after reading http://sphinx-doc.org/rest.html#images I thought this is exactly what I need. An automatic way to include image files as SVG in case of the web version and as PDF in case of the LaTeX version. The thing is that the described "wild card" method just does not work. I tested this thoroughly (I think) and when ever the file is explicitly referenced Sphinx will correctly copy the image file from the source to the destination (build/dirhtml/_images or build/latex). This works fine for SVG and for PDF.

However using the wild card method the files will neither be copied over nor will the links be used as relative to the source directory but it seems as relative to the location of the actual rst file.

Here the result of a small test case:

1. Case - include explicit svg: .. image:: /../docs-dir/Icons/foo.svg
2. Case - include implicit via wildcard: .. image:: /../docs-dir/Icons/foo.*
3. Case - try different path: .. image:: _images/foo.*

Server log:

• Case 1 reply:

127.0.0.1 - - [22/Jan/2014 13:54:35] "GET /_images/foo.svg HTTP/1.1" 200 -

• Case 2 reply:

127.0.0.1 - - [22/Jan/2014 13:54:35] code 404, message File not found
127.0.0.1 - - [22/Jan/2014 13:54:35] "GET /components/connectors/graphics/docs-dir/Icons/foo.svg HTTP/1.1" 404 -

• Case 3 reply

127.0.0.1 - - [22/Jan/2014 13:54:35] code 404, message File not found
127.0.0.1 - - [22/Jan/2014 13:54:35] "GET /components/connectors/graphics/_images/foo.* HTTP/1.1" 404 -

The version I'm using is:

~$ sphinx-build --version
Sphinx (sphinx-build) 1.2

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1358
• Originally reported by: Dietmar Winkler
• Originally created at: 2014-01-23T09:15:31.168

[shimizukawa]

From Dietmar Winkler on 2014-01-23 09:07:20+00:00

Some additional information:

1. the exact path in the image directive:

I've changed the directive to not use the /.. syntax but to use the path relative from the location of the rst file. Unfortunately to no avail:

Include explicit svg:

.. image:: ../../../docs-dir/Icons/foo.svg

Include implicit via wildcard:

.. image::  ../../../docs-dir/Icons/foo.*

Server log:

127.0.0.1 - - [23/Jan/2014 09:57:01] "GET /_images/foo.svg HTTP/1.1" 200 -
127.0.0.1 - - [23/Jan/2014 09:57:01] code 404, message File not found
127.0.0.1 - - [23/Jan/2014 09:57:01] "GET /components/connectors/graphics/docs-dir/Icons/foo.svg HTTP/1.1" 404 -

2. the path of the .rst document it's in

text/source/components/connectors/graphics.rst

3. the path of the image file

text/docs-dir/Icons/foo.svg
text/docs-dir/Icons/foo.pdf

[shimizukawa]

From Georg Brandl on 2014-01-23 09:08:58+00:00

ok. So I suppose the "conf.py" is in test/source?

[shimizukawa]

From Dietmar Winkler on 2014-01-23 09:10:51+00:00

Correct! (well in text/source)

[shimizukawa]

From Georg Brandl on 2014-01-23 09:24:22+00:00

Closes #1358: Fix handling of image paths outside of the source directory when using the "wildcard" style reference.

→ <<cset 4ab5d6e>>

[shimizukawa]

From Georg Brandl on 2014-01-23 09:25:01+00:00

OK, that was unfortunate, but at least it will be fixed in 1.2.2.

[shimizukawa]

From Dietmar Winkler on 2014-01-23 09:43:39+00:00

Tested and confirmed fixed with d0629b0.

[shimizukawa]

From Dietmar Winkler on 2014-04-12 22:40:00+00:00

Looks like this has to be reopened as it still does not work when using the LaTeX exporter.

LaTeX Warning: File `ModelicaByExample/Components/SpeedMeasurement/Examples/Pla
ntWithPulseCounter.*' not found on input line 1327.
! LaTeX Error: Unknown graphics extension: .*.

For the HTML exporter it links correctly to the SVG version of that file.

[shimizukawa]

From Dietmar Winkler on 2014-04-12 22:40:32+00:00

Still does not work for the LaTeX exporter

[shimizukawa]

From Dietmar Winkler on 2014-04-12 22:57:45+00:00

My bad. The reason was a non-existing file.

[shimizukawa]

From Andrea Cassioli on 2014-08-29 09:41:51+00:00

Hi,
the docs actually refer to an automatic selection among PDF and PNG. Could it be better clarify? Moreover, is there an option to set the default image type for a builder?

[shimizukawa]

From Takayuki Shimizukawa on 2014-08-29 12:22:17+00:00

Andrea Cassioli this is the logic to select image type:

#1: define supported image types that ordered by priority for each builders. for about html builder:

sphinx/sphinx/builders/html.py

Line 76 in f190de7

supported_image_types = ['image/svg+xml', 'image/png',

#2: collect image candidates

sphinx/sphinx/environment.py

Line 783 in f190de7

def process_images(self, docname, doctree):

#3: Pick the best candidate for all image URIs.

sphinx/sphinx/builders/__init__.py

Line 153 in f190de7

def post_process_images(self, doctree):

There is no way to specify the default image type.

[shimizukawa]

From Andrea Cassioli on 2014-08-29 12:42:46+00:00

I see. Should I assume that

supported_image_types = ['image/svg+xml', 'image/png',
'image/gif', 'image/jpeg']

reflects the order in which image formats are selected? I guess it is common to store the same image in different format.

However, I was actually suggesting to clarify how this works in the docs. But thank you for the explanation.

[shimizukawa]

From Takayuki Shimizukawa on 2014-08-29 14:21:30+00:00

Yes. your guessing is correct.

I'll add documentation for that.

[shimizukawa]

From Takayuki Shimizukawa on 2014-08-29 14:21:54+00:00

Add documentation for supported image types and choosing priority for each builders. refs #1358.

→ <>