diff --git a/doc/conf.py b/doc/conf.py index 39ba1db6cda..1ce78b421f0 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/contributing.md b/doc/contributing.md index 910ebd7e590..035cc44675d 100644 --- a/doc/contributing.md +++ b/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 = ` to any place (usually at the top) in the tutorial. The *fig_number* starts from 1. diff --git a/doc/index.rst b/doc/index.rst index 88ffce2a705..6d34e27b28c 100644 --- a/doc/index.rst +++ b/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 diff --git a/examples/tutorials/README.txt b/examples/tutorials/README.txt index 0c7e28c3b35..4ae40011e79 100644 --- a/examples/tutorials/README.txt +++ b/examples/tutorials/README.txt @@ -1,2 +1,6 @@ +.. _tutorials: + Tutorials ========= + +These examples teach us how to complete various tasks using PyGMT! diff --git a/examples/tutorials/3d_perspective_image.py b/examples/tutorials/advanced/3d_perspective_image.py similarity index 100% rename from examples/tutorials/3d_perspective_image.py rename to examples/tutorials/advanced/3d_perspective_image.py diff --git a/examples/tutorials/advanced/README.txt b/examples/tutorials/advanced/README.txt new file mode 100644 index 00000000000..4519ce7c669 --- /dev/null +++ b/examples/tutorials/advanced/README.txt @@ -0,0 +1,2 @@ +Advanced +-------- diff --git a/examples/tutorials/configuration.py b/examples/tutorials/advanced/configuration.py similarity index 100% rename from examples/tutorials/configuration.py rename to examples/tutorials/advanced/configuration.py diff --git a/examples/tutorials/contour_map.py b/examples/tutorials/advanced/contour_map.py similarity index 100% rename from examples/tutorials/contour_map.py rename to examples/tutorials/advanced/contour_map.py diff --git a/examples/tutorials/date_time_charts.py b/examples/tutorials/advanced/date_time_charts.py similarity index 99% rename from examples/tutorials/date_time_charts.py rename to examples/tutorials/advanced/date_time_charts.py index 31e40c32585..fbb26e90442 100644 --- a/examples/tutorials/date_time_charts.py +++ b/examples/tutorials/advanced/date_time_charts.py @@ -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 `. +# refer to :doc:`frame instructions `. # # The other important item in the ``frame`` list is # ``"sxa1Of1D"``. This string modifies the secondary diff --git a/examples/tutorials/earth_relief.py b/examples/tutorials/advanced/earth_relief.py similarity index 100% rename from examples/tutorials/earth_relief.py rename to examples/tutorials/advanced/earth_relief.py diff --git a/examples/tutorials/insets.py b/examples/tutorials/advanced/insets.py similarity index 100% rename from examples/tutorials/insets.py rename to examples/tutorials/advanced/insets.py diff --git a/examples/tutorials/subplots.py b/examples/tutorials/advanced/subplots.py similarity index 100% rename from examples/tutorials/subplots.py rename to examples/tutorials/advanced/subplots.py diff --git a/examples/tutorials/vectors.py b/examples/tutorials/advanced/vectors.py similarity index 100% rename from examples/tutorials/vectors.py rename to examples/tutorials/advanced/vectors.py diff --git a/examples/tutorials/basics/README.txt b/examples/tutorials/basics/README.txt new file mode 100644 index 00000000000..b76022bb84e --- /dev/null +++ b/examples/tutorials/basics/README.txt @@ -0,0 +1,2 @@ +Basics +------ diff --git a/examples/tutorials/coastlines.py b/examples/tutorials/basics/coastlines.py similarity index 100% rename from examples/tutorials/coastlines.py rename to examples/tutorials/basics/coastlines.py diff --git a/examples/tutorials/first_figure.py b/examples/tutorials/basics/first_figure.py similarity index 100% rename from examples/tutorials/first_figure.py rename to examples/tutorials/basics/first_figure.py diff --git a/examples/tutorials/frames.py b/examples/tutorials/basics/frames.py similarity index 100% rename from examples/tutorials/frames.py rename to examples/tutorials/basics/frames.py diff --git a/examples/tutorials/lines.py b/examples/tutorials/basics/lines.py similarity index 100% rename from examples/tutorials/lines.py rename to examples/tutorials/basics/lines.py diff --git a/examples/tutorials/plot.py b/examples/tutorials/basics/plot.py similarity index 100% rename from examples/tutorials/plot.py rename to examples/tutorials/basics/plot.py diff --git a/examples/tutorials/regions.py b/examples/tutorials/basics/regions.py similarity index 100% rename from examples/tutorials/regions.py rename to examples/tutorials/basics/regions.py diff --git a/examples/tutorials/text.py b/examples/tutorials/basics/text.py similarity index 100% rename from examples/tutorials/text.py rename to examples/tutorials/basics/text.py diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 4c441e03628..f90e55f2eba 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -18,7 +18,7 @@ "R": r""" region : str or list *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*]. - Specify the :doc:`region ` of interest.""", + Specify the :doc:`region ` 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 `. """, + :doc:`frame and axes attributes `. """, "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 ` of interest. + Specify the :doc:`region ` of interest. projection : str *projcode*\[*projparams*/]\ *width*. Select map :doc:`projection `. diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index a4e7646f60f..404fc490cc0 100644 --- a/pygmt/src/grdview.py +++ b/pygmt/src/grdview.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 ` 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 ` 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.