From b2b3d1f7de27b97029cf1db129c56fa44c134458 Mon Sep 17 00:00:00 2001 From: Will Schlitzer Date: Fri, 12 Mar 2021 05:13:30 +0000 Subject: [PATCH] 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 Co-authored-by: Michael Grund Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> Co-authored-by: Yao Jiayuan Co-authored-by: Meghan Jones --- doc/conf.py | 15 +++++++++------ doc/index.rst | 2 +- examples/gallery/3d_plots/README.txt | 2 ++ .../gallery/{grid => 3d_plots}/grdview_surface.py | 0 examples/gallery/{plot => 3d_plots}/scatter3d.py | 0 examples/gallery/coast/README.txt | 2 -- examples/gallery/embellishments/README.txt | 2 ++ .../gallery/{plot => embellishments}/colorbar.py | 0 .../gallery/{plot => embellishments}/inset.py | 0 .../gallery/{plot => embellishments}/legend.py | 0 examples/gallery/{plot => embellishments}/logo.py | 0 examples/gallery/grid/README.txt | 2 -- examples/gallery/images/README.txt | 2 ++ examples/gallery/{plot => images}/image.py | 0 .../gallery/{grid => images}/track_sampling.py | 0 examples/gallery/line/README.txt | 2 -- examples/gallery/lines/README.txt | 2 ++ .../line_custom_cpt.py} | 0 examples/gallery/{line => lines}/linestyles.py | 0 .../vector_heads_tails.py} | 2 +- examples/gallery/{line => lines}/vectors.py | 2 +- examples/gallery/maps/README.txt | 2 ++ examples/gallery/{coast => maps}/borders.py | 0 .../gallery/{coast => maps}/land_and_water.py | 0 examples/gallery/{coast => maps}/shorelines.py | 0 examples/gallery/plot/README.txt | 2 -- examples/gallery/seismology/README.txt | 2 ++ examples/gallery/{plot => seismology}/meca.py | 0 examples/gallery/symbols/README.txt | 2 ++ .../datetime_inputs.py} | 0 .../multi_parameter_symbols.py} | 0 examples/gallery/{plot => symbols}/points.py | 0 .../points_transparency.py} | 0 examples/gallery/{plot => symbols}/scatter.py | 0 examples/tutorials/{inset.py => insets.py} | 0 examples/tutorials/lines.py | 2 +- 36 files changed, 27 insertions(+), 18 deletions(-) create mode 100644 examples/gallery/3d_plots/README.txt rename examples/gallery/{grid => 3d_plots}/grdview_surface.py (100%) rename examples/gallery/{plot => 3d_plots}/scatter3d.py (100%) delete mode 100644 examples/gallery/coast/README.txt create mode 100644 examples/gallery/embellishments/README.txt rename examples/gallery/{plot => embellishments}/colorbar.py (100%) rename examples/gallery/{plot => embellishments}/inset.py (100%) rename examples/gallery/{plot => embellishments}/legend.py (100%) rename examples/gallery/{plot => embellishments}/logo.py (100%) delete mode 100644 examples/gallery/grid/README.txt create mode 100644 examples/gallery/images/README.txt rename examples/gallery/{plot => images}/image.py (100%) rename examples/gallery/{grid => images}/track_sampling.py (100%) delete mode 100644 examples/gallery/line/README.txt create mode 100644 examples/gallery/lines/README.txt rename examples/gallery/{line/line-custom-cpt.py => lines/line_custom_cpt.py} (100%) rename examples/gallery/{line => lines}/linestyles.py (100%) rename examples/gallery/{line/vector-heads-tails.py => lines/vector_heads_tails.py} (98%) rename examples/gallery/{line => lines}/vectors.py (96%) create mode 100644 examples/gallery/maps/README.txt rename examples/gallery/{coast => maps}/borders.py (100%) rename examples/gallery/{coast => maps}/land_and_water.py (100%) rename examples/gallery/{coast => maps}/shorelines.py (100%) delete mode 100644 examples/gallery/plot/README.txt create mode 100644 examples/gallery/seismology/README.txt rename examples/gallery/{plot => seismology}/meca.py (100%) create mode 100644 examples/gallery/symbols/README.txt rename examples/gallery/{plot/datetime-inputs.py => symbols/datetime_inputs.py} (100%) rename examples/gallery/{plot/multi-parameter-symbols.py => symbols/multi_parameter_symbols.py} (100%) rename examples/gallery/{plot => symbols}/points.py (100%) rename examples/gallery/{plot/points-transparency.py => symbols/points_transparency.py} (100%) rename examples/gallery/{plot => symbols}/scatter.py (100%) rename examples/tutorials/{inset.py => insets.py} (100%) diff --git a/doc/conf.py b/doc/conf.py index 9583ed7f8a4..25d044bdac4 100644 --- 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 index 7dcc11b8953..dbb64e0c822 100644 --- 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 new file mode 100644 index 00000000000..580c258215f --- /dev/null +++ b/examples/gallery/3d_plots/README.txt @@ -0,0 +1,2 @@ +3D Plots +-------- diff --git a/examples/gallery/grid/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py similarity index 100% rename from examples/gallery/grid/grdview_surface.py rename to examples/gallery/3d_plots/grdview_surface.py diff --git a/examples/gallery/plot/scatter3d.py b/examples/gallery/3d_plots/scatter3d.py similarity index 100% rename from examples/gallery/plot/scatter3d.py rename to examples/gallery/3d_plots/scatter3d.py diff --git a/examples/gallery/coast/README.txt b/examples/gallery/coast/README.txt deleted file mode 100644 index a45d2747e61..00000000000 --- a/examples/gallery/coast/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -Coastlines and boundaries -------------------------- diff --git a/examples/gallery/embellishments/README.txt b/examples/gallery/embellishments/README.txt new file mode 100644 index 00000000000..3a6e2b21482 --- /dev/null +++ b/examples/gallery/embellishments/README.txt @@ -0,0 +1,2 @@ +Plot embellishments +------------------- diff --git a/examples/gallery/plot/colorbar.py b/examples/gallery/embellishments/colorbar.py similarity index 100% rename from examples/gallery/plot/colorbar.py rename to examples/gallery/embellishments/colorbar.py diff --git a/examples/gallery/plot/inset.py b/examples/gallery/embellishments/inset.py similarity index 100% rename from examples/gallery/plot/inset.py rename to examples/gallery/embellishments/inset.py diff --git a/examples/gallery/plot/legend.py b/examples/gallery/embellishments/legend.py similarity index 100% rename from examples/gallery/plot/legend.py rename to examples/gallery/embellishments/legend.py diff --git a/examples/gallery/plot/logo.py b/examples/gallery/embellishments/logo.py similarity index 100% rename from examples/gallery/plot/logo.py rename to examples/gallery/embellishments/logo.py diff --git a/examples/gallery/grid/README.txt b/examples/gallery/grid/README.txt deleted file mode 100644 index 6fd2c9aea1a..00000000000 --- a/examples/gallery/grid/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -Grids ------ diff --git a/examples/gallery/images/README.txt b/examples/gallery/images/README.txt new file mode 100644 index 00000000000..3375172a820 --- /dev/null +++ b/examples/gallery/images/README.txt @@ -0,0 +1,2 @@ +Images, contours, and fields +---------------------------- diff --git a/examples/gallery/plot/image.py b/examples/gallery/images/image.py similarity index 100% rename from examples/gallery/plot/image.py rename to examples/gallery/images/image.py diff --git a/examples/gallery/grid/track_sampling.py b/examples/gallery/images/track_sampling.py similarity index 100% rename from examples/gallery/grid/track_sampling.py rename to examples/gallery/images/track_sampling.py diff --git a/examples/gallery/line/README.txt b/examples/gallery/line/README.txt deleted file mode 100644 index 043f6ca6a79..00000000000 --- a/examples/gallery/line/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -Lines ------ diff --git a/examples/gallery/lines/README.txt b/examples/gallery/lines/README.txt new file mode 100644 index 00000000000..8e2076a6c6d --- /dev/null +++ b/examples/gallery/lines/README.txt @@ -0,0 +1,2 @@ +Lines and vectors +----------------- diff --git a/examples/gallery/line/line-custom-cpt.py b/examples/gallery/lines/line_custom_cpt.py similarity index 100% rename from examples/gallery/line/line-custom-cpt.py rename to examples/gallery/lines/line_custom_cpt.py diff --git a/examples/gallery/line/linestyles.py b/examples/gallery/lines/linestyles.py similarity index 100% rename from examples/gallery/line/linestyles.py rename to examples/gallery/lines/linestyles.py diff --git a/examples/gallery/line/vector-heads-tails.py b/examples/gallery/lines/vector_heads_tails.py similarity index 98% rename from examples/gallery/line/vector-heads-tails.py rename to examples/gallery/lines/vector_heads_tails.py index 366ee58beda..7c213f73006 100644 --- a/examples/gallery/line/vector-heads-tails.py +++ b/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 `) +:doc:`Vector types documentation `) by passing the corresponding shortcuts to the ``style`` parameter. """ diff --git a/examples/gallery/line/vectors.py b/examples/gallery/lines/vectors.py similarity index 96% rename from examples/gallery/line/vectors.py rename to examples/gallery/lines/vectors.py index 480cd9cb89b..7dc6d7042f9 100644 --- a/examples/gallery/line/vectors.py +++ b/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 `. +:doc:`Vector attributes documentation `. """ import numpy as np diff --git a/examples/gallery/maps/README.txt b/examples/gallery/maps/README.txt new file mode 100644 index 00000000000..b1a00a492fb --- /dev/null +++ b/examples/gallery/maps/README.txt @@ -0,0 +1,2 @@ +Maps and map elements +--------------------- diff --git a/examples/gallery/coast/borders.py b/examples/gallery/maps/borders.py similarity index 100% rename from examples/gallery/coast/borders.py rename to examples/gallery/maps/borders.py diff --git a/examples/gallery/coast/land_and_water.py b/examples/gallery/maps/land_and_water.py similarity index 100% rename from examples/gallery/coast/land_and_water.py rename to examples/gallery/maps/land_and_water.py diff --git a/examples/gallery/coast/shorelines.py b/examples/gallery/maps/shorelines.py similarity index 100% rename from examples/gallery/coast/shorelines.py rename to examples/gallery/maps/shorelines.py diff --git a/examples/gallery/plot/README.txt b/examples/gallery/plot/README.txt deleted file mode 100644 index c213e06feea..00000000000 --- a/examples/gallery/plot/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -Plotting map items ------------------- diff --git a/examples/gallery/seismology/README.txt b/examples/gallery/seismology/README.txt new file mode 100644 index 00000000000..9f247d8f474 --- /dev/null +++ b/examples/gallery/seismology/README.txt @@ -0,0 +1,2 @@ +Seismology and geodesy +---------------------- diff --git a/examples/gallery/plot/meca.py b/examples/gallery/seismology/meca.py similarity index 100% rename from examples/gallery/plot/meca.py rename to examples/gallery/seismology/meca.py diff --git a/examples/gallery/symbols/README.txt b/examples/gallery/symbols/README.txt new file mode 100644 index 00000000000..8d8d751404e --- /dev/null +++ b/examples/gallery/symbols/README.txt @@ -0,0 +1,2 @@ +Symbols and markers +------------------- diff --git a/examples/gallery/plot/datetime-inputs.py b/examples/gallery/symbols/datetime_inputs.py similarity index 100% rename from examples/gallery/plot/datetime-inputs.py rename to examples/gallery/symbols/datetime_inputs.py diff --git a/examples/gallery/plot/multi-parameter-symbols.py b/examples/gallery/symbols/multi_parameter_symbols.py similarity index 100% rename from examples/gallery/plot/multi-parameter-symbols.py rename to examples/gallery/symbols/multi_parameter_symbols.py diff --git a/examples/gallery/plot/points.py b/examples/gallery/symbols/points.py similarity index 100% rename from examples/gallery/plot/points.py rename to examples/gallery/symbols/points.py diff --git a/examples/gallery/plot/points-transparency.py b/examples/gallery/symbols/points_transparency.py similarity index 100% rename from examples/gallery/plot/points-transparency.py rename to examples/gallery/symbols/points_transparency.py diff --git a/examples/gallery/plot/scatter.py b/examples/gallery/symbols/scatter.py similarity index 100% rename from examples/gallery/plot/scatter.py rename to examples/gallery/symbols/scatter.py diff --git a/examples/tutorials/inset.py b/examples/tutorials/insets.py similarity index 100% rename from examples/tutorials/inset.py rename to examples/tutorials/insets.py diff --git a/examples/tutorials/lines.py b/examples/tutorials/lines.py index a7340371aee..c844367cacb 100644 --- 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(