Sphinx warns about not readable image file (although the image is found for html build)
See original GitHub issueI’m currently trying to port the doc of scikit-image to sphinx-gallery (see https://github.com/scikit-image/scikit-image/pull/2078).
During the html build of the doc, sphinx issues the following warning (treated as error by CI):
/home/emma/travail/projects/scikit-image/doc/source/user_guide/numpy_images.rst:None:
WARNING: image file not readable: user_guide/../../_images/sphx_glr_plot_camera_numpy_001.png
sphx_glr_plot_camera_numpy_001.png
is generated by one of the examples of the gallery, and included in numpy_images.rst
as
.. image:: ../../_images/sphx_glr_plot_camera_numpy_001.png
:width: 45%
:target: ../auto_examples/numpy_operations/plot_camera_numpy.html
From the warning, it seems that the path is wrong, but the html page generated from the build displays correctly the image (and the link to the gallery example works too). Therefore, I don’t understand the origin of the warning (and maybe I wouldn’t mind it so much if didn’t make our Travis CI fail 😃).
This path issue might be another facet of the problem of having a separated source
directory, as also illustrated in #115, but I’m not sure whether that point matters here.
Issue Analytics
- State:
- Created 7 years ago
- Comments:13 (13 by maintainers)
Top GitHub Comments
That’s closing an issue a bit fast, IMHO. The problem is that we had a fairly senior Python developer not managing to use sphinx-gallery right after giving it a good try. If she is not managing by her own, it means that there is something wrong with either our documentation, or our error messages, or our configuration file.
My point is that sphinx-gallery is currently tricky to use because it requires working in a certain way and outside this chartered territory things don’t work. We don’t realize it because all the projects that we use it for are somewhat clones of each other with regards to the documentation. However it’s quite a barrier to entry, as @emmanuelle has been finding out when trying to use it on scikit-image.
Before we discard this issue, we need to figure out how to make sure that users don’t fall in this trap again.
@Titan-C thanks for the comments and explanations. About the comment style + renaming, my point was not to question the choices of
sphinx-gallery
. Instead, I tried to give you a flavor of the migration process for a not-so-new package such as scikit-image.