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 <seisman.info@gmail.com>
Co-authored-by: Michael Grund <michael_grund@gmx.de>
Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
Co-authored-by: Yao Jiayuan <coreman.seism@gmail.com>
Co-authored-by: Meghan Jones <meghanj@hawaii.edu>

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