scale image in stead of make thumbnail and independent backrefereces function #26

Titan-C · 2015-04-11T13:51:11Z

Here I refactor in 3 things.

First I include the change from the mayavi branch that turns make thumbnail into scale image
Second I split the backreferece file generation into a separate function
Last the fhindex is no more moved around the gen_dir_rst functions it is now a return value

agramfort · 2015-04-11T14:31:49Z

sphinxgallery/gen_rst.py

@@ -244,7 +241,25 @@ def _thumbnail_div(subdir, full_dir, fname, snippet):
    return out


-def generate_dir_rst(directory, fhindex, examples_dir, gallery_dir, gallery_conf, plot_gallery, seen_backrefs):
+def write_backreferces(backrefs, seen_backrefs, gallery_conf,


write_backreferces ? I don't understand.

… on generate_file_rst

…o work properly

Titan-C · 2015-05-01T14:41:17Z

sphinxgallery/backreferences.py

+    <div class="sphx-glr-thumbContainer" tooltip="{}">
+
+.. figure:: /{}
+    :target: /{}.html


This is the target directive to put links to the figure. It would be great if it could take references and not links urls

Probably very naive: but it seems that removing the leading / in the target fixes the link without running a webserver. Is there a reason why you need it?

Same thing goes for the / in figure, it doesn't look like it is needed.

Probably very naive: but it seems that removing the leading / in the target fixes the link without running a webserver. Is there a reason why you need it?

It doesn't solve it for me. Which sphinx version are you using? I have 1.2.3
I use the leading / because it allows me to link to the image from any location in the documentation. And if used for the target when running the web server it also links properly from anywhere.

I guess I was right, it was a very naive attempt! I think it may have fixed the link in the backreferences but not in the gallery or the other way around. I'll try to take a closer look.

FWIW the documentation says the target can take reference but I was unable to get it to work, maybe because it is not supposed to work across documents.

In general, it would be a lot better if a webserver wasn't needed to look at the documentation.

In general, it would be a lot better if a webserver wasn't needed to look at the documentation.

+1000

Yes, I also agree on that. Although once published online I doesn't do much of a difference. The thing I fear is that it will require to extended sphinx to accept the :doc: or :ref: directive inside the figure environment. at target can only take urls or same page references. And I'm still trying to figure out how does sphinx work at this level.

Titan-C · 2015-05-01T15:01:58Z

@lesteve this is the broken or almost working branch. If you build the documentation you will notice that in the gallery all the links on the images are broken, but not their caption. Nevertheless if you run a webserver on _build/html these links work. This is the problem of the target directive. See comment in code.

What does this have to do with backreferences? Backrefences are the exact same thumbnails of the gallery but put at the end of the modules documentation API(Feature only used by scikit-learn), so one has to link to the same example website but from different locations(the Gallery and the documented API) The scikit-learn solution was to make _thumbnail_div take 2 input dirs. One having the directory of the gallery and the other containing the relative path from the API documentation to the gallery. But that requires to hardcode those relative locations in the script. And that shall not be done for a generic module, as every user would locate their files to his convenience.

The problem of the back references is how to keep track of the location of the gallery example files and images and how to link to them from an arbitrary location. My solution was to use sphinx absolute paths to the sphinx source directory. So I would only need to know the example files location, sphinx does the rest. This can be used for the figure directive which searches within sphinx, but the target directive takes urls. So if a webserver is used on the _build/html or any output directory, then all absolute paths work.

lesteve · 2015-05-04T18:59:49Z

The scikit-learn solution was to make _thumbnail_div take 2 input dirs. One having the directory of the gallery and the other containing the relative path from the API documentation to the gallery. But that requires to hardcode those relative locations in the script.

Why can't we keep doing the same thing with two directories arguments? In particular it would be great if you could point me to the hardcoding needed in the scikit-learn code.

GaelVaroquaux · 2015-05-04T19:10:53Z

Why can't we keep doing the same thing with two directories arguments?

+1

Titan-C · 2015-05-04T19:16:33Z

Why can't we keep doing the same thing with two directories arguments? In particular it would be great if you could point me to the hardcoding needed in the scikit-learn code?

So the _thumbnail_div processes the directories separately here: https://github.com/scikit-learn/scikit-learn/blob/master/doc/sphinxext/gen_rst.py#L584-590

but when one calls if for a gallery thumbnail one uses: https://github.com/scikit-learn/scikit-learn/blob/master/doc/sphinxext/gen_rst.py#L633

whereas for the backreferences. One codes where:

the examples are stored: https://github.com/scikit-learn/scikit-learn/blob/master/doc/sphinxext/gen_rst.py#L643
then you give the relative location of one to the other: https://github.com/scikit-learn/scikit-learn/blob/master/doc/sphinxext/gen_rst.py#L653-654
finally you only call the example file from a rst file in the same folder

GaelVaroquaux · 2015-05-04T19:20:49Z

Aren't these architectural problems that should be fixed, rather than
introducing fragile workarounds?

On Mon, May 04, 2015 at 12:16:34PM -0700, Óscar Nájera wrote:

Why can't we keep doing the same thing with two directories arguments? In
particular it would be great if you could point me to the hardcoding needed
in the scikit-learn code?
So the _thumbnail_div processes the directories separately here: https://
github.com/scikit-learn/scikit-learn/blob/master/doc/sphinxext/gen_rst.py#
L584-590

but when one calls if for a gallery thumbnail one uses: https://github.com/
scikit-learn/scikit-learn/blob/master/doc/sphinxext/gen_rst.py#L633

whereas for the backreferences. One codes where:

• the examples are stored: https://github.com/scikit-learn/scikit-learn/blob/
master/doc/sphinxext/gen_rst.py#L643
• then you give the relative location of one to the other: https://github.com
/scikit-learn/scikit-learn/blob/master/doc/sphinxext/gen_rst.py#L653-654
• finally you only call the example file from a rst file in the same folder

—
Reply to this email directly or view it on GitHub.*

Gael Varoquaux
Researcher, INRIA Parietal
NeuroSpin/CEA Saclay , Bat 145, 91191 Gif-sur-Yvette France
Phone:  ++ 33-1-69-08-79-68
http://gael-varoquaux.info            http://twitter.com/GaelVaroquaux

Titan-C · 2015-05-04T19:56:57Z

Aren't these architectural problems that should be fixed, rather than introducing fragile workarounds?

yes. That's why I wanted to use absolute paths. But I run short of the capabilities of sphinx when the figure instruction can only take links as urls or local references, and not cross references across documents like ref or absolute paths to rst files like doc.

lesteve · 2015-05-06T13:05:32Z

doc/reference.rst

+.. include:: modules/generated/sphinxgallery.__version__.examples
+.. raw:: html
+
+        <div style='clear:both'></div>


Is this clearing needed and if yes should it be added to the .examples file directly?

Also maybe not in this PR but it'd be great to use sphinx templates as scikit-learn is doing in order to introduce the .examples automatically and have an example within sphinx-gallery showing this feature.

It is required maybe 90% because one is floating the thumbnails and one has to signalize when that ends. 10% when it is not needed is because the theme of the website is simple enough it has no conflict with the floats. The basic/default sphinx theme, which you render locally is immune. The read the docs theme, and scikit-learn where many other divs are floated need this. But it is all your choice on the theme you use.
I'm not sure if it should be added to the .example file directly. If one uses the sphinx templates for documenting modules and classes(as in scikit-learn) I guess it is better to add it manually there and once. All because it is more a theme and style instruction. If you change the CSS of sphinx-gallery and its floats, then this becomes irrelevant or more the user choice.

Out of interest, what is the worse that can happen if you always use the clearing trick, even when not needed ?

.example files are automatically generated so I don't really see a problem to add the clearing there. At least it ensures that just doing an include will just work and you don't have to remember to add the raw html additional content.

Out of interest, what is the worse that can happen if you always use the clearing trick, even when not needed ?

I have no idea. It is CSS.

.example files are automatically generated so I don't really see a problem to add the clearing there

I'll put the clearing

GaelVaroquaux · 2015-05-06T21:29:06Z

In the end the solution looks is very simple and elegant. I first extend the figure directive with a custom one to hold the gallery thumbnails.

I really don't like the extension of a directive. The whole design of the original gen_rst.py is to avoid this. Sphinx directives have prooved to be fragile and to break. Please absolutely avoid creating sphinx directives and absolute imports.

Titan-C · 2015-05-06T21:45:47Z

@GaelVaroquaux would you take over this PR. I really don't see a more simpler solution that gets the job done. Besides relying on absolute paths and running always on a webserver. Indeed having an extra directive, although simple, does feel like an overshoot, but I could not get a better solution.

GaelVaroquaux · 2015-05-06T21:53:31Z

@GaelVaroquaux would you take over this PR. I really don't see a more simpler solution that gets the job done. Besides relying on absolute paths and running always on a webserver. Indeed having an extra directive, although simple, does feel like an overshoot, but I could not get a better solution.

You have no idea how overbooked I am. There is no chance that I can take over this PR. I don't know how we got to this situation, but the first versions of gen_rst.py did not need such hacks. I suspect that it's a new feature that is calling for those hacks. Well, maybe it's time to cut our loses and decide that we don't want this feature. All I am saying is that those hacks should not get in the project because they will make the codebase too fragile.

Titan-C · 2015-05-07T14:34:10Z

This can not get any simpler, I should have gotten this idea in the first place. Instead of putting a link to the image in the thumbnail. The anchor in the caption is extended in CSS to cover the complete thumbnail area. So the references get properly resolved by sphinx, and the link is not only over the text but on the whole thumbnail. No sphinx extensions, only CSS tricks.

lesteve · 2015-05-08T19:13:00Z

This seems to be working fine indeed, good stuff!

Out of interest, can you explain how it works? My question is mostly how come you can now click anywhere on the thumbnail to go to the example page? In other words why the target of the <a ..> element is available on one of its parent element?

GaelVaroquaux · 2015-05-08T21:29:12Z

could you try to use only relative imports when imprint things from sphinxgallery to make it easier to embed the code

GaelVaroquaux · 2015-05-08T21:35:54Z

I had a quick look at this PR. Good job fixing the back reference difficulty! I like your solution very much!

Titan-C · 2015-05-09T21:07:54Z

could you try to use only relative imports when imprint things from sphinxgallery to make it easier to embed the code

are not relative imports being dropped in python3?

Titan-C · 2015-05-09T21:12:27Z

Out of interest, can you explain how it works? My question is mostly how come you can now click anywhere on the thumbnail to go to the example page? In other words why the target of the element is available on one of its parent element?

Well, that it why it did not occur to me in the beginning. In CSS you have to think of element arranged in layers, So it is not that the target of the element if available for its parent. But that the element is on a higher layer than the parent and it extends itself over the whole parent covering its entire surface.

GaelVaroquaux · 2015-05-09T21:31:13Z

could you try to use only relative imports when imprint things from
sphinxgallery to make it easier to embed the code

are not relative imports being dropped in python3?

No, it's rather the oppositive: imports are no longer relative by
default. In other words "import os" will never be equivalent to "from .
import os".

lesteve · 2015-05-14T22:49:04Z

I think this PR can go in. The CSS thing seems a little bit fragile but way more transparent than the sphinx directive and the backreference functionality is a great thing to have.

Titan-C · 2015-05-19T00:25:56Z

Sorry for the timeout, I wasn't around. I include some minor fixes based on the comments.

scale image in stead of make thumbnail independent backrefereces function with CSS templating to make complete gallery thumbnail area click-able relative imports for easier embedded code

agramfort reviewed Apr 11, 2015
View reviewed changes

Titan-C force-pushed the scim branch from fbf53bf to 459f385 Compare April 18, 2015 13:15

Titan-C force-pushed the scim branch from 54bc704 to 30a697f Compare May 1, 2015 09:02

Titan-C added 17 commits May 1, 2015 16:04

scale image instead of make thumbnail

a5e640c

path join

1172254

gen_gallery spacing and line lenght for pep8

7ea03a6

gen_rst spacing and line length for pep8

adc63a2

backreference writer is now a new function

321359d

Don't pass fhindex as an argument in generate_dir_rst

311c4ec

write_backreferences scans the source code on its own does not depend…

3b5051e

… on generate_file_rst

Absolute and relative paths in for thumbnail_div and backreferences t…

e8f2162

…o work properly

Reduce directory variable use, use src and target dirs only

a8c43fd

fix bug

8b06315

Extract backreference treatment to a separate module

99cd9ca

Use back references

255422a

separate rst example file generation from example script execution

c8de3d3

py2-3 print function

931f056

refactor clean image dir

3bf2197

Relative dirs

6c011d8

RST file style

87b0af9

Titan-C force-pushed the scim branch from 30a697f to 87b0af9 Compare May 1, 2015 14:05

Titan-C mentioned this pull request May 1, 2015

[MRG+2] Sphinx-gallery use scikit-learn/scikit-learn#4658

Merged

6 tasks

Titan-C reviewed May 1, 2015
View reviewed changes

gallery thumb directive redoes figure

ab876eb

lesteve reviewed May 6, 2015
View reviewed changes

Fix details

695b54f

Gallery thumbnail is CSS masked by anchor, solved by sphinx

ab9c241

remove import of glr_thumb module sphinx directive

4ab7293

Titan-C added 3 commits May 19, 2015 01:22

Use of relative imports

0fa790d

thumbnail image label suffix

040c935

Show feature of subfolder of examples

94440ae

Titan-C merged commit 6f14f84 into sphinx-gallery:master May 20, 2015

Titan-C deleted the scim branch May 20, 2015 08:03

Titan-C mentioned this pull request May 20, 2015

Add example scripts in 'examples' subfolders #32

Closed

Titan-C mentioned this pull request Nov 24, 2015

Modularize features #7

Closed

Titan-C mentioned this pull request Aug 27, 2018

sphinx-exhibit matplotlib/matplotlib#11936

Closed

scale image in stead of make thumbnail and independent backrefereces function #26

scale image in stead of make thumbnail and independent backrefereces function #26

Uh oh!

Conversation

Titan-C commented Apr 11, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GaelVaroquaux May 4, 2015 via email

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Titan-C commented May 1, 2015

Uh oh!

lesteve commented May 4, 2015

Uh oh!

GaelVaroquaux commented May 4, 2015

Uh oh!

Titan-C commented May 4, 2015

Uh oh!

GaelVaroquaux commented May 4, 2015

Uh oh!

Titan-C commented May 4, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GaelVaroquaux commented May 6, 2015 via email

Uh oh!

Titan-C commented May 6, 2015

Uh oh!

GaelVaroquaux commented May 6, 2015 via email

Uh oh!

Titan-C commented May 7, 2015

Uh oh!

lesteve commented May 8, 2015

Uh oh!

GaelVaroquaux commented May 8, 2015

Uh oh!

GaelVaroquaux commented May 8, 2015

Uh oh!

Titan-C commented May 9, 2015

Uh oh!

Titan-C commented May 9, 2015

Uh oh!

GaelVaroquaux commented May 9, 2015

Uh oh!

lesteve commented May 14, 2015

Uh oh!

Titan-C commented May 19, 2015

Uh oh!

Uh oh!