deploy: 1c4d845

Author: github-actions[bot]

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 0e9a6fcc67f2ddebd53c8efd65cafc2e
+tags: 645f666f9bcd5a90fca523b33c5a78b7

.nojekyll

@@ -0,0 +1,140 @@
+Contributors Guide
+------------------
+
+This is a community driven project and everyone is welcome to contribute. The
+project is hosted at the `gmt-examples GitHub repository <https://github.com/GenericMappingTools/gmt-examples>`_.
+
+The goal is to maintain a diverse community that's pleasant for everyone.
+**Please be considerate and respectful of others**. Everyone must abide by our
+`Code of Conduct <https://github.com/GenericMappingTools/gmt-examples/blob/main/CODE_OF_CONDUCT.md>`_
+and we encourage all to read it carefully.
+
+GMT Examples Overview
+~~~~~~~~~~~~~~~~~~~~~
+
+There are two main components to GMT examples project:
+
+* Gallery examples, with source material in the ``docs/gallery/`` folder.
+* Tutorial examples, with source material in the ``docs/tutorials/`` folder.
+
+The gallery examples are designed to instruct users on how to complete a specific
+problem. For general recommendations on how to design effective gallery examples,
+see the `diataxis framework's section on how-to guides <https://diataxis.fr/how-to-guides/>`_.
+
+The tutorials are learning orientated with the goal of teaching users GMT. For
+general recommendations on how to design effective tutorials, see the
+`diataxis framework's section on tutorials <https://diataxis.fr/tutorials/>`_.
+
+The documentation are written primarily in
+`reStructuredText <https://docutils.sourceforge.io/rst.html>`_ and built by
+`Sphinx <http://www.sphinx-doc.org/>`_. Please refer to
+:gmt-module:`reStructuredText cheatsheet <devdocs/rst-cheatsheet.html>` if you are new to reStructuredText.
+
+Setting up your environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following dependencies are required for building the GMT examples pages:
+
+- `gmt <https://docs.generic-mapping-tools.org/latest/>`_ (GMT is required for executing example scripts)
+- `sphinx <http://www.sphinx-doc.org/>`_ (a Python documentation generator for creating the docs from source files)
+- `sphinx_gmt <https://www.generic-mapping-tools.org/sphinx_gmt/latest/>`_ (a Sphinx extension for creating GMT figures to accompany example scripts)
+- `sphinx_rtd_theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`_ (a Sphinx theme used for consistent documentation appearance between GMT projects)
+
+Two options for installing the dependencies are :ref:`pip <Pip Setup>` and :ref:`conda <Conda Setup>`.
+Since Sphinx is a Python documentation generator, you will need a working Python
+environment. For those who do not already have a working Python environment,
+one option is to use the minimal installer for Conda `Miniforge <https://github.com/conda-forge/miniforge>`_
+along with the :ref:`conda <Conda Setup>` instructions.
+
+Pip Setup
+^^^^^^^^^
+
+These instructions rely on the `pip <https://pip.pypa.io/en/stable/>`_ package
+installer, which can be used to install all dependencies except GMT.
+Follow the `GMT Install Guide <https://github.com/GenericMappingTools/gmt/blob/master/INSTALL.md>`_
+to install GMT. The Python dependencies can be installed using the
+``requirements.txt`` from the base of the repository (you may wish to setup a
+`virtual environment <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`_ first):
+
+Unix/macOS::
+
+  python -m pip install -r requirements.txt
+
+Windows::
+
+  py -m pip install -r requirements.txt
+
+Conda Setup
+^^^^^^^^^^^
+
+These instructions rely on the `conda <https://docs.conda.io/en/latest/>`_ package
+manager. Run the following from the base of the repository to create a new conda
+environment from the ``environment.yml`` file::
+
+  conda env create
+
+Before building the documentation, you have to activate the environment
+(you'll need to do this every time you start a new terminal)::
+
+  conda activate gmt-examples
+
+Building the documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have :ref:`setup your environment <Setting up your environment>`, you can
+build the documentation using::
+
+  cd docs
+  make html
+
+Contributing New Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The source files for the gallery examples and tutorials are ``.rst`` files in
+``docs/`` that generate one or more figures using the
+`sphinx_gmt <https://www.generic-mapping-tools.org/sphinx_gmt/latest/)>`_
+extension. To add a new gallery example or tutorial:
+
+* If necessary, create a new sub-directory under ``docs/gallery/`` for a
+  gallery example section (e.g., ``basemaps/`` or ``plot_embellishments/``).
+* Create a new ``.rst`` file inside the appropriate sub-directory in
+  ``docs/gallery/`` or ``docs/tutorials/``.
+* Add a descriptive title and as much explanation as necessary.
+* Add hyperlinks to GMT modules using the ``gmt-module`` reStructuredText directive::
+
+  :gmt-module:`grdview`
+
+* Add hyperlinks to GMT module options by appending lower-case ``#<option>`` to
+  the ``gmt-module`` argument::
+
+  :gmt-module:`grdview#q`
+
+* Add as many figures as needed using the ``gmtplot`` directive:
+
+  ::
+
+    .. gmtplot::
+
+       gmt begin basemap png
+         gmt basemap -B -Rg -JH5c
+       gmt end show
+
+  The figures will be placed after the source code in the built documentation
+  by the ``sphinx_gmt`` extension.
+
+* Add the file to the appropriate section in ``docs/index.rst`` using the following
+  template:
+
+  ::
+
+    ```bash
+      -  .. image:: _images/<file-name>-gmtplot-0.png
+            :target: gallery/<section>/<file-name>.html
+            :width: 80%
+            :align: center
+
+         :doc:`gallery/<section>/<file-name>`
+    ```
+
+  Edit the number in the ``.. image:: ...`` line to show a different figure on the
+  index page.

_images/2243b82b814295af096d16766b3b0a3e.png

@@ -0,0 +1,23 @@
+Plotting a surface
+------------------
+
+:gmt-module:`grdview` can plot 3-D surfaces using the :gmt-module:`-Q <grdview#q>`
+parameter with the ``s`` directive. Here, we use :gmt-module:`grdmath` to create
+a netCDF file containing a grid for plotting.
+
+Note that the **-p** parameter here controls the azimuth and elevation angle of
+the view.
+
+We use the :gmt-module:`-B <grdview#b>` parameter twice - the first specifies
+the :math:`x`- and :math:`y`-axes frame attributes and the second specifies the
+:math:`z`-axis frame attributes using the ``z`` directive.
+
+The :gmt-module:`-I <grdview#i>` parameter specifies the illumination; here we
+use an azimuth of 45° using the ``+a`` modifier.
+
+.. gmtplot::
+
+   gmt grdmath -R-15/15/-15/15 -I0.3 X Y HYPOT DUP 2 MUL PI MUL 8 DIV COS EXCH NEG 10 DIV EXP MUL 0.001 SUB = example_grid.nc
+   gmt begin grdview_surface png
+      gmt grdview example_grid.nc -Ba5f1 -Bza5f1 -JX10C -JZ2c -Qs -Croma -p135/30 -I+a45
+   gmt end show

_images/4546e1b4bf691b3b38010ff66e835609.png

@@ -0,0 +1,101 @@
+GMT Tutorials and Examples
+==========================
+
+A collection of tutorials and short guides demonstrating how to complete
+various tasks using GMT.
+
+There are two main components to GMT examples project:
+
+* Gallery examples.
+* Tutorial examples.
+
+The gallery examples are designed to instruct users on how to complete a specific problem.
+They are how-to guides. It assumes you already know how to work with GMT.
+
+The tutorials are learning orientated with the goal of teaching users GMT. 
+They are designed to help beginners to understand how GMT works. 
+If you want to learn GMT you should start here. 
+
+.. toctree::
+   :hidden:
+   :glob:
+   :maxdepth: 2
+   :caption: Gallery
+
+   gallery/*/*
+
+.. toctree::
+   :hidden:
+   :glob:
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorials/*/*
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Development
+
+   contributing.rst
+
+.. cssclass:: gmtgallery
+
+
+Gallery
+-------
+
+Maps and map elements
+~~~~~~~~~~~~~~~~~~~~~
+
+Lines
+~~~~~
+
+Vectors
+~~~~~~~
+
+
+Symbols and markers
+~~~~~~~~~~~~~~~~~~~
+
+Images, contours, and fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+3d plots
+~~~~~~~~
+
+.. cssclass:: gmtgallery
+
+-  .. image:: _images/4546e1b4bf691b3b38010ff66e835609.png
+      :target: gallery/3d_plots/grdview_surface.html
+      :width: 80%
+      :align: center
+
+   :doc:`gallery/3d_plots/grdview_surface`
+
+Seismology and geodesy
+~~~~~~~~~~~~~~~~~~~~~~
+
+Basemaps
+~~~~~~~~
+
+Histograms
+~~~~~~~~~~
+
+Plot embellishments
+~~~~~~~~~~~~~~~~~~~
+
+Tutorials
+---------
+
+Basics
+~~~~~~
+
+.. cssclass:: gmtgallery
+
+-  .. image:: _images/67b8930e41c80cad1a26bc81920b6abe.png
+      :target: tutorials/basics/coastlines.html
+      :width: 80%
+      :align: center
+
+   :doc:`tutorials/basics/coastlines`

_images/580c6f3ad7f899c6733aa12f8765740c.png

@@ -0,0 +1,76 @@
+Coastlines and boarders
+-----------------------
+
+Plotting coastlines and boarders is handled by :gmt-module:`coast`.
+
+Shorelines
+~~~~~~~~~~
+
+Use the :gmt-module:`-W <coast#w>` parameter to plot only the shorelines:
+
+.. gmtplot::
+
+   gmt begin shorelines png
+      gmt coast -Rg -JW15c -B -W
+   gmt end show
+
+The shorelines are divided in 4 levels:
+
+1. coastline
+2. lakeshore
+3. island-in-lake shore
+4. lake-in-island-in-lake shore
+
+You can specify which level you want to plot by appending the level number and a
+GMT pen configuration to the :gmt-module:`-W <coast#w>` parameter. For example,
+to plot just the coastlines with 0.5 thickness and black lines:
+
+.. gmtplot::
+
+   gmt begin shorelines_levels png
+      gmt coast -Rg -JW15c -B -W1/0.5p,black
+   gmt end show
+
+You can specify multiple levels by using the :gmt-module:`-W <coast#w>`
+parameter more than once:
+
+.. gmtplot::
+
+   gmt begin shorelines_levels png
+      gmt coast -Rg -JW15c -B -W1/0.5p,black -W2/0.5,red
+   gmt end show
+
+Resolutions
+~~~~~~~~~~~
+
+The coastline database comes with 5 resolutions, which can be set using the
+:gmt-module:`-D <coast#d>` parameter. The resolution drops by 80% between levels:
+
+1. **c**: crude
+2. **l**: low
+3. **i**: intermediate
+4. **h**: high
+5. **f**: full
+
+.. gmtplot::
+
+   oahu="-158.3/-157.6/21.2/21.8"
+   gmt begin shorelines_resolutions png
+      for res in c, l, i, h, f
+      do
+          gmt coast -R${oahu} -JM5c -W1p -D${res} -X5c
+      done
+   gmt end show
+
+Land and water
+~~~~~~~~~~~~~~
+
+Use the :gmt-module:`-G <coast#g>` and :gmt-module:`-S <coast#s>` parameters to
+specify a fill color for land and water bodies. The colors can be given by name
+or hex codes:
+
+.. gmtplot::
+
+   gmt begin land_water png
+      gmt coast -Rg -JW15c -B -G#666666 -Sskyblue
+   gmt end show