Need instructions for adding a new example

[seisman]

We have no instructions explaining how to add examples to the GMT gallery. PR #3296 is a good examples showing what files need to be added/updated.

We should document it in CONTRIBUTING.md or in the doc/examples/README.examples file. I prefer the latter.

[KristofKoch]

I agree that this could be documented better. However I would prefer to have it in the wiki instead of some hidden file somewhere in the depths of the repo.

[seisman]

As per #3296, now it seems pretty straightforward to add a new example to the GMT gallery. For example, if we want to add a new example ex52, we need to:

1. create the subdirectory doc/examples/ex52
2. add the example script ex52.sh and the corresponding PS file ex52.ps in the subdirectory. Note that the script name and the PS name must be ex52.
3. Add the documentation for the example, i.e., doc/rst/source/gallery/ex52.rst.

In the example documentation file ex52.rst, use

.. literalinclude:: /_verbatim/ex52.txt
   :language: bash

to include the script into the documentation, and

.. figure:: /_images/ex52.*
   :width: 500 px
   :align: center

   title of the example figure [optional]

to include the image file into the documentation.

[seisman]

We need to decide where to put these instructions.

1. CONTRIBUTING.md
2. doc/examples/README.examples
3. wiki

Thoughts?

[KristofKoch]

After thinking about it a bit more I 'd like to add a fourth option to @seisman's list:

4. GMT's own documentation with links from CONTRIBUTING.md and doc/examples/README.examples

Reasoning: Adding an example might be one of the first contributions to GMT by a new user (it was at least my first contribution). Therefore I would argue the bar should be as low as possible. Not to flood GMT with silly examples but to explain the concepts behind the documentation as well. Basically a how-to or maybe even a tutorial.

I can only speak from the perspective of a first time contributor to a GitHub based project. It looks quite daunting when confronted with the git pull request workflow, the system how GMT is organized and build and reStructuredText all at once for the first time. It was a steep learning curve for me and I'm still relying on my cheatsheets to use GitHub.

I think this initial steep learning curve might be one of the biggest hurdles to transform GMT to a community-developed project as it might turn away most of the potential contributors right from the start. Therefore I would make this an fully fledged page in the documentation.

[stale]

This issue has been automatically marked as stale because it has not had activity in the last 90 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions.