Wish: directive to insert plots or link to example with thumbnail about sphinx-gallery HOT 4 OPEN

(Unless I'm mistaken:) Inserting plots from examples requires knowing the path that sphinx-gallery assigns the image. This is a poor abstraction, and it would be nicer if there were an sphinx-gallery-image directive which determines the path from other key information. Another useful directive would place a selected example gallery at any point in the documentation.

I think I can repurpose the sphinx extension that took care of resolving the backreferences link on the thumbnails to this time put the full figure plus the example link if @GaelVaroquaux doesn't object again to including more sphinx extensions.

One thing that should be solved before is around the discussion on nilearn/nilearn#592 on how the references to the examples should be labeled. Shall they be analogous in prefix like the images or only keep the full path name of the script file or something else. Up to now no image not reference renaming has been propagated into nilearn or scikit-learn, so we shall choose a good standard.

from sphinx-gallery.

I have a personal bias against sphinx directives because I have seen then break on upgrade of sphinx. Actually scikit-learn documentation is currently broken under latest sphinx, although I am not sure that it is related.

Sent from my phone. Please forgive brevity and mis spelling

On Jun 7, 2015, 02:14, at 02:14, jnothman [email protected] wrote:

(Unless I'm mistaken:) Inserting plots from examples requires knowing
the path that sphinx-gallery assigns the image. This is a poor
abstraction, and it would be nicer if there were an
sphinx-gallery-image directive which determines the path from other
key information. Another useful directive would place a selected
example gallery at any point in the documentation.

---

Reply to this email directly or view it on GitHub:
#38

from sphinx-gallery.

At least one of the sphinx 1.3 breakages is not handling headlines
containing hyperlinks. Given that this wasn't a problem in 1.3b2 it's an
issue of release management as well as an actual bug.

On 8 June 2015 at 14:43, Gael Varoquaux [email protected] wrote:

I have a personal bias against sphinx directives because I have seen then
break on upgrade of sphinx. Actually scikit-learn documentation is
currently broken under latest sphinx, although I am not sure that it is
related.

Sent from my phone. Please forgive brevity and mis spelling

On Jun 7, 2015, 02:14, at 02:14, jnothman [email protected]
wrote:

(Unless I'm mistaken:) Inserting plots from examples requires knowing
the path that sphinx-gallery assigns the image. This is a poor
abstraction, and it would be nicer if there were an
sphinx-gallery-image directive which determines the path from other
key information. Another useful directive would place a selected
example gallery at any point in the documentation.

---

Reply to this email directly or view it on GitHub:
#38

—
Reply to this email directly or view it on GitHub
#38 (comment)
.

from sphinx-gallery.

I'm not sure we want this, to propertly identify an image you'd need to know the examples dir, example filename, and image number. The only thing you currently need on top of that is the extension, which is always (by default at least) PNG. So I don't think we'd gain too much from the abstraction, and we'd add overhead for supporting the directive.

from sphinx-gallery.