Contributors Guide

This is a community driven project and everyone is welcome to contribute. The project is hosted at the gmt-examples GitHub repository.

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

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.

The documentation are written primarily in reStructuredText and built by Sphinx. Please refer to reStructuredText cheatsheet if you are new to reStructuredText.

Setting up your environment

The following dependencies are required for building the GMT examples pages:

gmt (GMT is required for executing example scripts)
sphinx (a Python documentation generator for creating the docs from source files)
sphinx_gmt (a Sphinx extension for creating GMT figures to accompany example scripts)
sphinx_rtd_theme (a Sphinx theme used for consistent documentation appearance between GMT projects)

Two options for installing the dependencies are pip and conda. 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 along with the conda instructions.

Pip Setup

These instructions rely on the pip package installer, which can be used to install all dependencies except GMT. Follow the GMT Install Guide 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 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 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 setup 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 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.