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]>

Author: 6 people

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

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
 

examples/gallery/3d_plots/README.txt

@@ -0,0 +1,2 @@
+3D Plots
+--------

examples/gallery/grid/grdview_surface.py renamed to examples/gallery/3d_plots/grdview_surface.py

@@ -0,0 +1,2 @@
+Plot embellishments
+-------------------

examples/gallery/plot/scatter3d.py renamed to examples/gallery/3d_plots/scatter3d.py

@@ -0,0 +1,2 @@
+Images, contours, and fields
+----------------------------

examples/gallery/coast/README.txt

@@ -0,0 +1,2 @@
+Lines and vectors
+-----------------

examples/gallery/embellishments/README.txt

@@ -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.
 
 """

examples/gallery/plot/colorbar.py renamed to examples/gallery/embellishments/colorbar.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

examples/gallery/plot/inset.py renamed to examples/gallery/embellishments/inset.py

@@ -0,0 +1,2 @@
+Maps and map elements
+---------------------

examples/gallery/plot/legend.py renamed to examples/gallery/embellishments/legend.py

@@ -0,0 +1,2 @@
+Seismology and geodesy
+----------------------

examples/gallery/plot/logo.py renamed to examples/gallery/embellishments/logo.py

@@ -0,0 +1,2 @@
+Symbols and markers
+-------------------

examples/gallery/grid/README.txt

@@ -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(