Reorganize gallery examples (#995)

Changes in this PR: - Reorganizes the gallery examples to have more specific categories - Sort gallery examples by "title" in each subsection - Use underscores in file and directory names Co-authored-by: Dongdong Tian <[email protected]> Co-authored-by: Michael Grund <[email protected]> Co-authored-by: Wei Ji <[email protected]> Co-authored-by: Yao Jiayuan <[email protected]> Co-authored-by: Meghan Jones <[email protected]>
GenericMappingTools · Mar 12, 2021 · b2b3d1f · b2b3d1f
1 parent 80b699d
commit b2b3d1f
Show file tree

Hide file tree

Showing 36 changed files with 27 additions and 18 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -9,7 +9,7 @@
 # isort: off
 from sphinx_gallery.sorting import (  # pylint: disable=no-name-in-module
     ExplicitOrder,
-    FileNameSortKey,
+    ExampleTitleSortKey,
 )
 from pygmt import __commit__, __version__
 from pygmt.sphinx_gallery import PyGMTScraper
@@ -71,10 +71,13 @@
     "gallery_dirs": ["gallery", "tutorials", "projections"],
     "subsection_order": ExplicitOrder(
         [
-            "../examples/gallery/line",
-            "../examples/gallery/coast",
-            "../examples/gallery/plot",
-            "../examples/gallery/grid",
+            "../examples/gallery/maps",
+            "../examples/gallery/lines",
+            "../examples/gallery/symbols",
+            "../examples/gallery/images",
+            "../examples/gallery/3d_plots",
+            "../examples/gallery/seismology",
+            "../examples/gallery/embellishments",
             "../examples/projections/azim",
             "../examples/projections/conic",
             "../examples/projections/cyl",
@@ -88,7 +91,7 @@
     # Remove the "Download all examples" button from the top level gallery
     "download_all_examples": False,
     # Sort gallery example by file name instead of number of lines (default)
-    "within_subsection_order": FileNameSortKey,
+    "within_subsection_order": ExampleTitleSortKey,
     # directory where function granular galleries are stored
     "backreferences_dir": "api/generated/backreferences",
     # Modules for which function level galleries are created.  In

diff --git a/doc/index.rst b/doc/index.rst
@@ -38,7 +38,7 @@
     tutorials/contour-map.rst
     tutorials/earth-relief.rst
     tutorials/3d-perspective-image.rst
-    tutorials/inset.rst
+    tutorials/insets.rst
     tutorials/subplots.rst
     tutorials/configuration.rst
 

diff --git a/examples/gallery/3d_plots/README.txt b/examples/gallery/3d_plots/README.txt
@@ -0,0 +1,2 @@
+3D Plots
+--------
diff --git a/examples/gallery/grid/grdview_surface.py → examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/grid/grdview_surface.py → examples/gallery/3d_plots/grdview_surface.py
diff --git a/examples/gallery/plot/scatter3d.py → examples/gallery/3d_plots/scatter3d.py b/examples/gallery/plot/scatter3d.py → examples/gallery/3d_plots/scatter3d.py
diff --git a/examples/gallery/coast/README.txt b/examples/gallery/coast/README.txt
diff --git a/examples/gallery/embellishments/README.txt b/examples/gallery/embellishments/README.txt
@@ -0,0 +1,2 @@
+Plot embellishments
+-------------------
diff --git a/examples/gallery/plot/colorbar.py → examples/gallery/embellishments/colorbar.py b/examples/gallery/plot/colorbar.py → examples/gallery/embellishments/colorbar.py
diff --git a/examples/gallery/plot/inset.py → examples/gallery/embellishments/inset.py b/examples/gallery/plot/inset.py → examples/gallery/embellishments/inset.py
diff --git a/examples/gallery/plot/legend.py → examples/gallery/embellishments/legend.py b/examples/gallery/plot/legend.py → examples/gallery/embellishments/legend.py
diff --git a/examples/gallery/plot/logo.py → examples/gallery/embellishments/logo.py b/examples/gallery/plot/logo.py → examples/gallery/embellishments/logo.py
diff --git a/examples/gallery/grid/README.txt b/examples/gallery/grid/README.txt
diff --git a/examples/gallery/images/README.txt b/examples/gallery/images/README.txt
@@ -0,0 +1,2 @@
+Images, contours, and fields
+----------------------------
diff --git a/examples/gallery/plot/image.py → examples/gallery/images/image.py b/examples/gallery/plot/image.py → examples/gallery/images/image.py
diff --git a/examples/gallery/grid/track_sampling.py → examples/gallery/images/track_sampling.py b/examples/gallery/grid/track_sampling.py → examples/gallery/images/track_sampling.py
diff --git a/examples/gallery/line/README.txt b/examples/gallery/line/README.txt
diff --git a/examples/gallery/lines/README.txt b/examples/gallery/lines/README.txt
@@ -0,0 +1,2 @@
+Lines and vectors
+-----------------
diff --git a/examples/gallery/line/line-custom-cpt.py → examples/gallery/lines/line_custom_cpt.py b/examples/gallery/line/line-custom-cpt.py → examples/gallery/lines/line_custom_cpt.py
diff --git a/examples/gallery/line/linestyles.py → examples/gallery/lines/linestyles.py b/examples/gallery/line/linestyles.py → examples/gallery/lines/linestyles.py
diff --git a/examples/gallery/line/vector-heads-tails.py → examples/gallery/lines/vector_heads_tails.py b/examples/gallery/line/vector-heads-tails.py → examples/gallery/lines/vector_heads_tails.py
@@ -26,7 +26,7 @@
 In the following we use the :meth:`pygmt.Figure.plot` method to plot vectors
 with individual heads and tails. We must specify the modifiers (together with
 the vector type, here ``v``, see also
-:doc:`Vector types documentation </gallery/line/vectors>`) 
+:doc:`Vector types documentation </gallery/lines/vectors>`)
 by passing the corresponding shortcuts to the ``style`` parameter.
 
 """

diff --git a/examples/gallery/line/vectors.py → examples/gallery/lines/vectors.py b/examples/gallery/line/vectors.py → examples/gallery/lines/vectors.py
@@ -4,7 +4,7 @@
 
 The :meth:`pygmt.Figure.plot` method can plot Cartesian, circular, and geographic vectors.
 The ``style`` parameter controls vector attributes. See also
-:doc:`Vector attributes documentation </gallery/line/vector-heads-tails>`.
+:doc:`Vector attributes documentation </gallery/lines/vector_heads_tails>`.
 
 """
 import numpy as np

diff --git a/examples/gallery/maps/README.txt b/examples/gallery/maps/README.txt
@@ -0,0 +1,2 @@
+Maps and map elements
+---------------------
diff --git a/examples/gallery/coast/borders.py → examples/gallery/maps/borders.py b/examples/gallery/coast/borders.py → examples/gallery/maps/borders.py
diff --git a/examples/gallery/coast/land_and_water.py → examples/gallery/maps/land_and_water.py b/examples/gallery/coast/land_and_water.py → examples/gallery/maps/land_and_water.py
diff --git a/examples/gallery/coast/shorelines.py → examples/gallery/maps/shorelines.py b/examples/gallery/coast/shorelines.py → examples/gallery/maps/shorelines.py
diff --git a/examples/gallery/plot/README.txt b/examples/gallery/plot/README.txt
diff --git a/examples/gallery/seismology/README.txt b/examples/gallery/seismology/README.txt
@@ -0,0 +1,2 @@
+Seismology and geodesy
+----------------------
diff --git a/examples/gallery/plot/meca.py → examples/gallery/seismology/meca.py b/examples/gallery/plot/meca.py → examples/gallery/seismology/meca.py
diff --git a/examples/gallery/symbols/README.txt b/examples/gallery/symbols/README.txt
@@ -0,0 +1,2 @@
+Symbols and markers
+-------------------
diff --git a/examples/gallery/plot/datetime-inputs.py → examples/gallery/symbols/datetime_inputs.py b/examples/gallery/plot/datetime-inputs.py → examples/gallery/symbols/datetime_inputs.py
diff --git a/...s/gallery/plot/multi-parameter-symbols.py → ...allery/symbols/multi_parameter_symbols.py b/...s/gallery/plot/multi-parameter-symbols.py → ...allery/symbols/multi_parameter_symbols.py
diff --git a/examples/gallery/plot/points.py → examples/gallery/symbols/points.py b/examples/gallery/plot/points.py → examples/gallery/symbols/points.py
diff --git a/examples/gallery/plot/points-transparency.py → ...es/gallery/symbols/points_transparency.py b/examples/gallery/plot/points-transparency.py → ...es/gallery/symbols/points_transparency.py
diff --git a/examples/gallery/plot/scatter.py → examples/gallery/symbols/scatter.py b/examples/gallery/plot/scatter.py → examples/gallery/symbols/scatter.py
diff --git a/examples/tutorials/inset.py → examples/tutorials/insets.py b/examples/tutorials/inset.py → examples/tutorials/insets.py
diff --git a/examples/tutorials/lines.py b/examples/tutorials/lines.py
@@ -125,7 +125,7 @@
 # example below, the line width is set to ``7p``, the color is set to ``green``, and the
 # line style is ``-.-`` (*dash dot dash*).
 #
-# For a gallery showing other ``pen`` settings, see :doc:`/gallery/line/linestyles`.
+# For a gallery showing other ``pen`` settings, see :doc:`/gallery/lines/linestyles`.
 
 fig = pygmt.Figure()
 fig.plot(
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Images, contours, and fields
		----------------------------