From 55ade6f6b0c5e589a43a59bca8c7d55569939f12 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 30 Jan 2021 23:06:18 -0500 Subject: [PATCH] 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 --- CONTRIBUTING.md | 23 ++++++++++++---------- doc/conf.py | 2 ++ examples/tutorials/3d-perspective-image.py | 1 + examples/tutorials/coastlines.py | 1 + examples/tutorials/configuration.py | 1 + examples/tutorials/contour-map.py | 1 + examples/tutorials/earth-relief.py | 1 + examples/tutorials/frames.py | 1 + examples/tutorials/lines.py | 1 + examples/tutorials/plot.py | 1 + examples/tutorials/text.py | 1 + 11 files changed, 24 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8793090b52c..05bc488d181 100644 --- a/CONTRIBUTING.md +++ b/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 = ` 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. diff --git a/doc/conf.py b/doc/conf.py index 65e5d39cd60..34d1d949ae4 100644 --- a/doc/conf.py +++ b/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 diff --git a/examples/tutorials/3d-perspective-image.py b/examples/tutorials/3d-perspective-image.py index 157bdde56d1..68a6bb4ca5d 100644 --- a/examples/tutorials/3d-perspective-image.py +++ b/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 diff --git a/examples/tutorials/coastlines.py b/examples/tutorials/coastlines.py index 0fdd6f021c5..65dff69ed43 100644 --- a/examples/tutorials/coastlines.py +++ b/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 diff --git a/examples/tutorials/configuration.py b/examples/tutorials/configuration.py index 35be16106d9..4a205abf571 100644 --- a/examples/tutorials/configuration.py +++ b/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 diff --git a/examples/tutorials/contour-map.py b/examples/tutorials/contour-map.py index 2d80af168ea..6cb83eba7cb 100644 --- a/examples/tutorials/contour-map.py +++ b/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 diff --git a/examples/tutorials/earth-relief.py b/examples/tutorials/earth-relief.py index 3c1fb8d5f13..c258e3e8e94 100644 --- a/examples/tutorials/earth-relief.py +++ b/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 diff --git a/examples/tutorials/frames.py b/examples/tutorials/frames.py index 3a01707549c..ad5a44ce2fc 100644 --- a/examples/tutorials/frames.py +++ b/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 diff --git a/examples/tutorials/lines.py b/examples/tutorials/lines.py index f1b10b8f7a9..7d1809c4e5f 100644 --- a/examples/tutorials/lines.py +++ b/examples/tutorials/lines.py @@ -4,6 +4,7 @@ Plotting lines is handled by :meth:`pygmt.Figure.plot`. """ +# sphinx_gallery_thumbnail_number = 3 import pygmt diff --git a/examples/tutorials/plot.py b/examples/tutorials/plot.py index 6d727e22df1..bd87cd8c9e6 100644 --- a/examples/tutorials/plot.py +++ b/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 diff --git a/examples/tutorials/text.py b/examples/tutorials/text.py index 2d5578130d2..d34f1911c61 100644 --- a/examples/tutorials/text.py +++ b/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