configure / mention sphinx reference prefix

[amueller]

It seems like the version currently on pypi prepends _sphx_glr_auto_examples_ to the example filename (though I'm not sure) when generating the sphinx/rst ref.
This doesn't seem to be documented (or I couldn't find it). I also couldn't find a way to change that.
I just upgraded my sphinx_gallery, and I'm wondering if I now need to change all the references.

[Titan-C]

Yes the prefix of examples and images was set to this long ago while introducing the notebook styled examples in PR #36 to properly give a namespace to the gallery examples and images and to support multiple galleries at the same time. There was a large wait period since that change an the release containing it v0.0.11 in mid-november I certainly forgot to specify this also as API breaking, same as PR #66 that renames the module to sphinx_gallery.

reference to examples are prefixed with sphx_glr then the full path to the example with os.sep replaced by underscore is appended. Yes you need to change your references. I do think we shall not be changing this any more, we discussed for quite a long time when planing the adoption of the gallery by NiLearn.

I'm not sure if we should expose this as something to be configurable by the user

[amueller]

ok, fair enough. It would be good to mention this somewhere in the docs though.
I needed to generate docs and grep to find out how I can link to the examples.

[amueller]

if we use sphinx gallery for scikit-learn, as we should, this will break all external links to examples -- unless we add a script creating symbolic links from the old version...
@GaelVaroquaux any opinions about that?

[Titan-C]

Yes this namespace change of the images and references is indeed what delayed the adoption of sphinx-gallery in scikit-learn scikit-learn/scikit-learn#4658 (comment), and to be honest for that PR I already did the rename. But that rename is not valid as it only was for images @lesteve was wise to put the merge on delay. As in the end the naming was changed again.

[GaelVaroquaux]

if we use sphinx gallery for scikit-learn, as we should, this will break all external links to examples -- unless we add a script creating symbolic links from the old version... @GaelVaroquaux any opinions about that?

There is a big upstart cost to it. But it's really the clean thing to do: it's basically a namespace, to avoid name collisions. I think that overall I support this design. The gains offset the costs. What are your thoughts?

[amueller]

yeah I'm fine with it.