Choosing the thumbnail figures in tutorials (#826)

Description of proposed changes

- Add comments # sphinx_gallery_thumbnail_number = X to tutorials and choose the best thumbnail images.
- Mention # sphinx_gallery_thumbnail_number = X in the contributing guide

Author: seisman

CONTRIBUTING.md

@@ -130,7 +130,7 @@ General guidelines for making a good gallery plot:
   dataset isn't available, open an issue requesting one and we'll work together to add
   it.
 * Add comments to explain things are aren't obvious from reading the code. Good: *Use a
-  Mercator projection and make the plot 15 centimeters wide*. Bad: *Draw coastlines and 
+  Mercator projection and make the plot 15 centimeters wide*. Bad: *Draw coastlines and
   plot the data*.
 * Describe the feature that you're showcasing and link to other relevant parts of the
   documentation.
@@ -147,6 +147,9 @@ The tutorials (the User Guide in the docs) are also built by sphinx-gallery from
 * Include the tutorial in the table of contents of the documentation (side bar). Do this
   by adding a line to the User Guide `toc` directive in `doc/index.rst`. Notice that the
   file included is the `.rst` generated by sphinx-gallery.
+* Choose the most representative figure as the thumbnail figure by adding a comment line
+  `# sphinx_gallery_thumbnail_number = <fig_number>` to any place (usually at the top)
+  in the tutorial. The *fig_number* starts from 1.
 
 Guidelines for a good tutorial:
 
@@ -156,7 +159,7 @@ Guidelines for a good tutorial:
   features or abbreviations.
 * Explain the options and features in as much detail as possible. The gallery has
   concise examples while the tutorials are detailed and full of text.
-* SI units should be used in the example code for tutorial plots.  
+* SI units should be used in the example code for tutorial plots.
 
 Note that the `Figure.show()` function needs to be called for a plot to be inserted into
 the documentation.
@@ -165,15 +168,15 @@ the documentation.
 
 When editing documentation, use the following standards to demonstrate the example code:
 
-1. Python arguments, such as import statements, Boolean expressions, and function 
+1. Python arguments, such as import statements, Boolean expressions, and function
    arguments should be wrapped as ``code`` by using \`\` on both sides of the code.
    Example: \`\`import pygmt\`\` results in ``import pygmt``
-   
-2.  Literal GMT arguments should be **bold** by wrapping the arguments with \*\* 
-    (two asterisks) on both sides. The argument description should be in *italicized* 
+
+2.  Literal GMT arguments should be **bold** by wrapping the arguments with \*\*
+    (two asterisks) on both sides. The argument description should be in *italicized*
     with \* (single asterisk) on both sides.
     Example: `**+l**\ *label*` results in **+l***label*
-    
+
 3. Optional arguments are placed wrapped with [ ] (square brackets).
 4. Arguments that are mutually exclusive are separated with a | (bar) to denote "or".
 
@@ -319,9 +322,9 @@ existing functionality.
 Tests also help us be confident that we won't break your code in the future.
 
 When writing tests, don't test everything that the GMT function already tests, such as
-the every unique combination arguments. An exception to this would be the most popular 
-modules, such as `plot` and `basemap`. The highest priority for tests should be the 
-Python-specific code, such as numpy, pandas, and xarray objects and the virtualfile 
+the every unique combination arguments. An exception to this would be the most popular
+modules, such as `plot` and `basemap`. The highest priority for tests should be the
+Python-specific code, such as numpy, pandas, and xarray objects and the virtualfile
 mechanism.
 
 If you're **new to testing**, see existing test files for examples of things to do.

doc/conf.py

@@ -89,6 +89,8 @@
     # Insert links to documentation of objects in the examples
     "reference_url": {"pygmt": None},
     "image_scrapers": (PyGMTScraper(),),
+    # Removes configuration comments from scripts
+    "remove_config_comments": True,
 }
 
 # Sphinx project configuration

examples/tutorials/3d-perspective-image.py

@@ -5,6 +5,7 @@
 Create 3-D perspective image or surface mesh from a grid
 using :meth:`pygmt.Figure.grdview`.
 """
+# sphinx_gallery_thumbnail_number = 7
 
 import pygmt
 

examples/tutorials/coastlines.py

@@ -4,6 +4,7 @@
 
 Plotting coastlines and borders is handled by :meth:`pygmt.Figure.coast`.
 """
+# sphinx_gallery_thumbnail_number = 5
 
 import pygmt
 

examples/tutorials/configuration.py

@@ -4,6 +4,7 @@
 
 Default GMT parameters can be set globally or locally using :class:`pygmt.config`.
 """
+# sphinx_gallery_thumbnail_number = 3
 
 import pygmt
 

examples/tutorials/contour-map.py

@@ -4,6 +4,7 @@
 
 Plotting a contour map is handled by :meth:`pygmt.Figure.grdcontour`.
 """
+# sphinx_gallery_thumbnail_number = 5
 
 import pygmt
 

examples/tutorials/earth-relief.py

@@ -6,6 +6,7 @@
 :meth:`pygmt.datasets.load_earth_relief` method. The data can then be plotted using the
 :meth:`pygmt.Figure.grdimage` method.
 """
+# sphinx_gallery_thumbnail_number = 5
 
 import pygmt
 

examples/tutorials/frames.py

@@ -5,6 +5,7 @@
 Setting the style of the map frames, ticks, etc, is handled by the ``frame`` argument
 that all plotting methods of :class:`pygmt.Figure`.
 """
+# sphinx_gallery_thumbnail_number = 4
 
 import pygmt
 

examples/tutorials/lines.py

@@ -4,6 +4,7 @@
 
 Plotting lines is handled by :meth:`pygmt.Figure.plot`.
 """
+# sphinx_gallery_thumbnail_number = 3
 
 import pygmt
 

examples/tutorials/plot.py

@@ -8,6 +8,7 @@
 automatically downloaded and saved to a cache directory the first time you use them
 (usually ``~/.gmt/cache``).
 """
+# sphinx_gallery_thumbnail_number = 3
 
 import pygmt
 

examples/tutorials/text.py

@@ -5,6 +5,7 @@
 It is often useful to add annotations to a map plot. This is handled by
 :meth:`pygmt.Figure.text`.
 """
+# sphinx_gallery_thumbnail_number = 3
 
 import os