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_design (A sphinx extension for designing beautiful, screen-size responsive web-components)
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/
orplot_embellishments/
).Create a new
.rst
file inside the appropriate sub-directory indocs/gallery/
ordocs/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 thegmt-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:.. grid-item-card:: :doc:`gallery/<section>/<file-name>` :padding: 1 :link-type: doc :link: gallery/<section>/<file-name> .. image:: _images/<image-hash>.png
Edit the hash in the
.. image:: ...
line to show a different figure on the index page.