Reorganize tutorial section in the documentation sidebar (#1603)

Co-authored-by: Wei Ji <[email protected]>

Author: Meghan Jones

doc/conf.py

@@ -87,6 +87,8 @@
             "../examples/projections/misc",
             "../examples/projections/nongeo",
             "../examples/projections/table",
+            "../examples/tutorials/basics",
+            "../examples/tutorials/advanced",
         ]
     ),
     # Patter to search for example files

doc/contributing.md

@@ -343,12 +343,9 @@ General guidelines for making a good gallery plot:
 The tutorials (the User Guide in the docs) are also built by sphinx-gallery from the
 `.py` files in the `examples/tutorials` folder of the repository. To add a new tutorial:
 
-* Include a `.py` file in the `examples/tutorials` folder on the base of the repository.
+* Create a `.py` file in the `examples/tutorials/advanced` folder.
 * Write the tutorial in "notebook" style with code mixed with paragraphs explaining what
   is being done. See the other tutorials for the format.
-* 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 = <fig_number>` to any place (usually at the top)
   in the tutorial. The *fig_number* starts from 1.

doc/index.rst

@@ -20,36 +20,17 @@
 
     overview.rst
     install.rst
-    tutorials/first_figure.rst
-
-.. toctree::
-    :maxdepth: 2
-    :hidden:
-    :caption: Examples
-
-    gallery/index.rst
-    external_resources.md
+    tutorials/basics/first_figure.rst
 
 .. toctree::
     :maxdepth: 2
     :hidden:
     :caption: User Guide
 
-    tutorials/frames.rst
+    tutorials/index.rst
+    gallery/index.rst
     projections/index.rst
-    tutorials/coastlines.rst
-    tutorials/regions.rst
-    tutorials/plot.rst
-    tutorials/lines.rst
-    tutorials/vectors.rst
-    tutorials/date_time_charts.rst
-    tutorials/text.rst
-    tutorials/contour_map.rst
-    tutorials/earth_relief.rst
-    tutorials/3d_perspective_image.rst
-    tutorials/insets.rst
-    tutorials/subplots.rst
-    tutorials/configuration.rst
+    external_resources.md
 
 .. toctree::
     :maxdepth: 2

examples/tutorials/README.txt

@@ -1,2 +1,6 @@
+.. _tutorials:
+
 Tutorials
 =========
+
+These examples teach us how to complete various tasks using PyGMT!

examples/tutorials/3d_perspective_image.py renamed to examples/tutorials/advanced/3d_perspective_image.py

@@ -0,0 +1,2 @@
+Advanced
+--------

examples/tutorials/advanced/README.txt

@@ -11,7 +11,7 @@
 The following examples will demonstrate how to create plots
 using the different datetime objects.
 """
-# sphinx_gallery_thumbnail_number = 0
+# sphinx_gallery_thumbnail_number = 8
 
 import datetime
 
@@ -285,7 +285,7 @@
 # Starting off with ``WS``, adding this string means that only
 # Western/Left (**W**) and Southern/Bottom (**S**) borders of
 # the plot will be shown. For more information on this, please
-# refer to :doc:`frame instructions </tutorials/frames>`.
+# refer to :doc:`frame instructions </tutorials/basics/frames>`.
 #
 # The other important item in the ``frame`` list is
 # ``"sxa1Of1D"``. This string modifies the secondary

examples/tutorials/configuration.py renamed to examples/tutorials/advanced/configuration.py

@@ -0,0 +1,2 @@
+Basics
+------

examples/tutorials/contour_map.py renamed to examples/tutorials/advanced/contour_map.py

@@ -18,7 +18,7 @@
     "R": r"""
         region : str or list
             *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
-            Specify the :doc:`region </tutorials/regions>` of interest.""",
+            Specify the :doc:`region </tutorials/basics/regions>` of interest.""",
     "J": r"""
         projection : str
             *projcode*\[*projparams*/]\ *width*.
@@ -34,7 +34,7 @@
     "B": r"""
         frame : bool or str or list
             Set map boundary
-            :doc:`frame and axes attributes </tutorials/frames>`. """,
+            :doc:`frame and axes attributes </tutorials/basics/frames>`. """,
     "U": """\
         timestamp : bool or str
             Draw GMT time stamp logo on plot.""",
@@ -447,7 +447,7 @@ def fmt_docstring(module_func):
         tabular data.
     region : str or list
         *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
-        Specify the :doc:`region </tutorials/regions>` of interest.
+        Specify the :doc:`region </tutorials/basics/regions>` of interest.
     projection : str
         *projcode*\[*projparams*/]\ *width*.
         Select map :doc:`projection </projections/index>`.

examples/tutorials/date_time_charts.py renamed to examples/tutorials/advanced/date_time_charts.py

@@ -61,10 +61,10 @@ def grdview(self, grid, **kwargs):
         DataArray.
     region : str or list
         *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
-        Specify the :doc:`region </tutorials/regions>` of interest. When used
-        with ``perspective``, optionally append */zmin/zmax* to indicate the
-        range to use for the 3-D axes [Default is the region in the input
-        grid].
+        Specify the :doc:`region </tutorials/basics/regions>` of interest.
+        When used with ``perspective``, optionally append */zmin/zmax* to
+        indicate the range to use for the 3-D axes [Default is the region in
+        the input grid].
     {J}
     zscale/zsize : float or str
         Set z-axis scaling or z-axis size.