Allow user to choose thumbnail image #114

adrn · 2016-03-26T23:22:35Z

This implements a way for the example-writer to specify which figure is displayed as the thumbnail when an example script generates multiple figures.

This is a bit of a hack and may not make sense to merge in as is, but it's at least something to start discussion. The basic idea with this implementation is that inside the docstring of a given example script, you can add a key:value pair, e.g., thumbnail: 3 that specifies which figure in a given example to display as the thumbnail.

Like I said: this is a hack. Right now, this uses a regexp to pick out the "thumbnail:" block. A nicer way to move forward might be to think about how you want to represent module-level, arbitrary configuration data or metadata in example files. Then, this thumbnail tag could just fit in that way. Thoughts welcome!

cc @keflavich

… thumbnail

adrn · 2016-03-30T15:52:08Z

This is a trial implementation to solve #110

lesteve · 2016-03-31T07:47:53Z

Using the docstring for this seems as good as other ideas that were floated to be honest ! Some tests are failing though, haven't looked into it in more details.

We would need some tests for the extract_thumbnail_number function.

If you want to cater for the more general case (although this is probably YAGNI unless you have something in mind already), you could use something like:

"""
docstring

metadata={'thumbail_figure_number': 1}
"""

GaelVaroquaux · 2016-03-31T16:43:46Z

I'd rather use a comment, because if we use the docstring, the info will be printed in the text of the example.

lesteve · 2016-03-31T17:03:45Z

I'd rather use a comment, because if we use the docstring, the info will be printed in the text of the example.

Fair point actually for examples that do print(__doc__) ...

GaelVaroquaux · 2016-03-31T17:05:09Z

Fair point actually for examples that do print(doc) ...

But also because it's rendered in the html.

lesteve · 2016-03-31T17:21:54Z

But also because it's rendered in the html.

I think the thumbnail: line is stripped off the docstring by this PR so it should not appear in the HTML.

adrn · 2016-03-31T18:17:05Z

Yea, the line is just deleted from of the docstring before displaying with a regular expression. If we change the key name from thumbnail to something like sphinx_gallery_thumbnail_number then I think it'd be sufficiently specific that we can do that. I'm fine with putting it in a comment too though. I'll add some tests and fix the build error. Thanks for the comments!

lesteve · 2016-04-13T09:18:59Z

@adrn have you managed to investigate the Travis errors? We chatted with @Titan-C and think it's better to put this in a comment that can be anywhere in the file even if that means having to read the file entirely once more. We favour something like (better naming suggestions welcome):

# sphinx_gallery_thumbnail_number = 3

lesteve · 2016-04-13T09:25:01Z

examples/plot_choose-thumbnail.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-


If you could name this file plot_choose_thumbnail.py with underscores, it would be more consistent.

adrn · 2016-04-13T13:08:53Z

Cool, working on this now. Any thoughts on 0-indexing? e.g., should the default / first plot be sphinx_gallery_thumbnail_number = 0 or sphinx_gallery_thumbnail_number = 1?

Edit: never mind -- it should be the latter because it corresponds to the number in the saved plot file.

adrn · 2016-04-13T13:31:20Z

Fixed the errors and made it search in a comment instead of the docstring as you suggested. Let me know if you think this needs anything else!

lesteve · 2016-04-13T13:51:40Z

sphinx_gallery/gen_rst.py

+    """ Pull out the thumbnail image number specified in the docstring. """
+
+    # check whether the user has specified a specific thumbnail image
+    pattr = re.compile("^#\s*sphinx_gallery_thumbnail_number:\s*([0-9]+)\s*$", flags=re.MULTILINE)


I would use = rather than :.

Really? this looks funny to me:

# sphinx_gallery_thumbnail_number = 2 # Code source: Óscar Nájera # License: BSD 3 clause

Hmmm then maybe move the sphinx_gallery_thumbnail_number it somewhere else in the file ;-)

lesteve · 2016-04-13T14:30:10Z

sphinx_gallery/gen_rst.py

    docstring, rest_of_content = get_docstring_and_rest(source_file)
+    rest_of_content, thumbnail_number = extract_thumbnail_number(rest_of_content)


You don't change rest_of_content anymore so you only need to return the thumbnail number from extract_thumbnail_number.

lesteve · 2016-04-13T14:59:48Z

sphinx_gallery/tests/test_gen_rst.py

+            f.write('\n'.join(['"Docstring"',
+                               test_str]))
+            f.flush()
+            _,cfg = sg.split_code_and_text_blocks(f.name)


Another PEP8 with space after the comma here.

adrn · 2016-04-13T15:35:27Z

Could you restart the travis build?

lesteve · 2016-04-13T15:46:02Z

Could you restart the travis build?

You can do git commit --amend and then force-push to trigger a new build.

adrn · 2016-04-13T15:50:14Z

It's a single button to package maintainers -- in other projects I contribute to, that is the desired way to trigger new builds...but ok, I can force-push if that is what you prefer here

(mainly to avoid any accidents with force-push)

Titan-C · 2016-04-13T20:12:46Z

looks good to me
Could you please write a line in CHANGES.rst, and a documentation section in doc/advanced_configuration.rst narrating how to use this feature and the link to the example using it.

lesteve · 2016-04-14T08:32:44Z

sphinx_gallery/gen_rst.py


+    docstring, rest_of_content = get_docstring_and_rest(source_file)


Avoiding unnecessary changes like this one is always appreciated.

adrn · 2016-04-14T12:12:57Z

@Titan-C Added documentation and addressed comments from @lesteve

lesteve · 2016-04-14T12:26:23Z

doc/advanced_configuration.rst

@@ -203,6 +203,23 @@ file. You need to add to the configuration dictionary a key called
        'default_thumb_file'     : 'path/to/thumb/file.png'}}


+choosing the thumbnail image from multiple figures


Capital needed for the title

lesteve · 2016-04-14T12:39:34Z

doc/advanced_configuration.rst

+
+    sphinx_gallery_thumbnail_number = 2
+
+The default behavior is ``sphinx_gallery_thumbnail_number = 1``. See


I would remove "The default behavior is sphinx_gallery_thumbnail_number = 1" since you already mention that the default is to pick the first figure above.

Said in words and said in code. I disagree.

lesteve · 2016-04-14T13:38:07Z

LGTM, merging, thanks a lot for this, in particular tackling all the minor comments that quickly !

adrn · 2016-04-14T13:45:45Z

👍 thanks for reviewing!

adrn added 3 commits March 26, 2016 15:59

hack to let user choose thumbnail figure

4b58a07

add example of how to choose which figure is displayed as the example…

4de89d4

… thumbnail

add docstring for extract function

13c65bb

adrn mentioned this pull request Mar 26, 2016

Add gallery of examples to documentation astropy/astropy#4734

Closed

10 tasks

lesteve reviewed Apr 13, 2016
View reviewed changes

rename to be consistent with other examples

ba01031

adrn added 3 commits April 13, 2016 09:19

extract comment not docstring line

07f3970

fix broken tests

da48fcc

fix conflicts

5373865

lesteve reviewed Apr 13, 2016
View reviewed changes

adrn added 6 commits April 13, 2016 10:06

don't remove thumbnail comment

45a372c

use nose assert_equal

207a0da

fix pep8 issue

f56623b

add explanatory comment about thumbnail choice

4a35ec4

use equal sign instead of colon

f2f50b3

fix colon in example file

0c40140

lesteve reviewed Apr 13, 2016
View reviewed changes

remove thumbnail reading from split_code_and_text_blocks

fe6f979

change first_image_file to image_file

84bdea7

adrn force-pushed the choose-thumbnail branch from c2d9a08 to 84bdea7 Compare April 13, 2016 15:52

lesteve reviewed Apr 14, 2016
View reviewed changes

adrn added 4 commits April 14, 2016 07:54

minor style changes

a10d684

change image path

9265fc0

change comment above thumbnail comment in example

2430839

add line to changes and add documentation section

dc2c56a

lesteve reviewed Apr 14, 2016
View reviewed changes

adrn added 2 commits April 14, 2016 08:37

fix typo in docs and minor suggestions

f9e71a4

typo

ab2af75

lesteve reviewed Apr 14, 2016
View reviewed changes

lesteve merged commit 3357bca into sphinx-gallery:master Apr 14, 2016

prisae mentioned this pull request Feb 12, 2020

thumbnails from loaded figures #607

Closed

		docstring, rest_of_content = get_docstring_and_rest(source_file)
		rest_of_content, thumbnail_number = extract_thumbnail_number(rest_of_content)

		@@ -203,6 +203,23 @@ file. You need to add to the configuration dictionary a key called
		'default_thumb_file' : 'path/to/thumb/file.png'}}


		choosing the thumbnail image from multiple figures


		sphinx_gallery_thumbnail_number = 2

		The default behavior is ``sphinx_gallery_thumbnail_number = 1``. See

Allow user to choose thumbnail image #114

Allow user to choose thumbnail image #114

Uh oh!

Conversation

adrn commented Mar 26, 2016

Uh oh!

adrn commented Mar 30, 2016

Uh oh!

lesteve commented Mar 31, 2016

Uh oh!

GaelVaroquaux commented Mar 31, 2016 via email

Uh oh!

lesteve commented Mar 31, 2016

Uh oh!

GaelVaroquaux commented Mar 31, 2016

Uh oh!

lesteve commented Mar 31, 2016

Uh oh!

adrn commented Mar 31, 2016

Uh oh!

lesteve commented Apr 13, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrn commented Apr 13, 2016

Uh oh!

adrn commented Apr 13, 2016

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!

adrn commented Apr 13, 2016

Uh oh!

lesteve commented Apr 13, 2016

Uh oh!

adrn commented Apr 13, 2016

Uh oh!

Titan-C commented Apr 13, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrn commented Apr 14, 2016

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!

lesteve commented Apr 14, 2016

Uh oh!

adrn commented Apr 14, 2016

Uh oh!

Uh oh!