As far I can see from the nilearn doc, we use things like:

.. image:: ../auto_examples/01_plotting/images/sphx_glr_plot_atlas_001.png
   :target: ../auto_examples/01_plotting/plot_atlas.html

Can you try to follow a pattern like this and see whether that fixes the warning?

I am not going to claim I understand how sphinx works in detail, but at one point I understood that the _images folder was something that sphinx was creating automatically by looking at all the images referenced to and copying them there. It could well be that your image is referenced correctly in the example HTML causing it to end up in _images. This would kind of explain why the image is not found at sphinx generation time but shows up correctly in the HTML.

Thank you so much for helping me dive into sphinx's black magics :-) ! It worked, warning fixed, made my day!

Glad to hear that! Closing this issue then.

Glad to hear that! Closing this issue then.

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.

@GaelVaroquaux well, even pretty senior developers do silly mistakes from time to time. Here I only had to change the name of the image (plot_camera_numpy_1.png to sphx_glr_plot_camera_numpy_001.png) and for some reason I don't remember I also changed the directory, using the `_images``directory generated by sphinx.

One problem that I have with sphinx (I guess I'm not the only one) is that it does a lot of magics about paths, filenames, references etc., so that I find it easy to get trapped in a local minimum of energy where you fixed some issues but you still didn't do it "the right way".

Anyway, for this issue it was really more me being stupid than the problem of sphinx-gallery (of course the problem was triggered by the fact that I had to rename the file name, but...).

The issue of #115 is much more serious IMO and might require a better solution than the quick fix of #119.

To document a little bit the process of porting a project to sphinx-gallery, here are the most time-consuming steps that I had to take so far

• rewrite comment blocks in notebook-style examples, that were all between triple quotes in our gallery, whereas sphinx-gallery wants #. I did this using a mixture of home-brewed parser + some manual cleaning.
• modify all references to images and examples in the narrative documentation, because names had changed.
• and (but this is bug-fixing) figuring out issues related to Is it possible to use sphinx-gallery with a separate source directory? #115, first to build the gallery, and then to generate links in examples.

All the rest was quite easy and well documented (what to add to conf.py for example).

@GaelVaroquaux I do make clean quite often with the same intention, and the problem persisted even after removing the build directory. But I got confused because the build generated two copies of the same image file, in two directories (not a problem of scikit-image, nilearn does the same).

Here I only had to change the name of the image
(plot_camera_numpy_1.png to sphx_glr_plot_camera_numpy_001.png) and
for some reason I don't remember I also changed the directory, using
the _images`directory generated by sphinx.

Yes we introduced the prefix in the images some versions ago in
Sphinx-Gallery to better deal with a Sphinx behavior of filling up the
_images directory. So this was a necessary step.

the _images directory is because sphinx copies all images to this
directory and redirects all links of images in there. In fact one should
never put links to this directory as it is generated during build, thus
sphinx can't find links to it while generating documentation(it exist in
_build and not in your source). On has to put relative paths(or webpage
absolute paths) from the file having the link to the image.

One problem that I have with sphinx (I guess I'm not the only one) is
that it does a lot of magics about paths, filenames, references etc.,
so that I find it easy to get trapped in a local minimum of energy
where you fixed some issues but you still didn't do it "the right
way".

Yes Sphinx has a lot of black magic and issues in it, not only with
paths. I suffered a lot when allowing sphinx-gallery to have a folder
structure different from scikit-learn and making the backreferences work
on this arbitrary filestructure.

Anyway, for this issue it was really more me being stupid than the
problem of sphinx-gallery (of course the problem was triggered by the
fact that I had to rename the file name, but...).

Yes, we prefixed generated images, is for the best.

• rewrite comment blocks in notebook-style examples, that were all
  between triple quotes in our gallery, whereas sphinx-gallery wants
  #. I did this using a mixture of home-brewed parser + some manual
  cleaning.

This is painful I agree, but your the # comments do seem cleaner. Since
scikit-learn or Nilearn did not have notebook examples before, this was
not an issue then. And maybe it shall not present an issue to new
users. I do guess having in code comments with # is way more common than
with triple quotes.

• modify all references to images and examples in the narrative
  documentation, because names had changed.

Yes, everything generated by sphinx-gallery prefixes sphx_glr,
namespaces are necessary to avoid conflicts.

I do make clean quite often with the same intention,
and the problem persisted even after removing the build directory. But
I got confused because the build generated two copies of the same
image file, in two directories (not a problem of scikit-image, nilearn
does the same).
This is Sphinx in action. Sphinx-Gallery saves the images locally in the
source directory in an images folder in the same directory to each
example rst file.
Then while generating html from rst files and writing all to the
_build/html sphinx copies all images to _build/html/_images

One shall always make the links to the local files in the source
directory. Even for the generated images from the examples, as they are
created in the source directory.

Hum, should sphinx-gallery have a clean mechanism? We tend to think
not, because when switching from one branch to another in a project
development, we don't want to clean stuff that is valid in another
branch.

Yes, we want to cache as much of the gallery builds during
development. And when #97 is merged it'll be even better(examples are
only rebuild if they failed previously of example changed).

There is on cleanup we do and is to remove all images generated by the
gallery from _build/html/_images. This is an "issue" with sphinx(is
developed like that on purpose) and specially nasty if you used the
matplotlib sphinx extension for plots. Because sphinx never deletes
files _build/html/_images, it just writes new files with new names so
this directory just grows. Thus some links to images failed after the
first build. But is working fine now as far as we are aware.

@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.