Add a page for simple examples

[seisman]

Description of proposed changes

As mentioned in #4448 and #3320, the current 52 examples in the Gallery page are a little too complicated.

Users may find that simple examples are more useful to learn GMT quickly. For example, both the PyGMT Gallery and the GMT.jl Gallery provides many simple examples. Users may also want to contribute simple examples rather than complicated ones (e.g., #4448 and #3320).

In this PR, I create a new gallery page for simple examples. The new page is called "Examples", and the old "Example Gallery" page is renamed to "Gallery" (We can change them to other names after some discussions).

The "Gallery" page contains complicated examples, and the scripts are located in the doc/examples directory.

The new "Examples" page contains simple examples (e.g., plotting lines with different styles). Each example is stored in the doc/rst/source/examples/exXXX directory. Each directory should contain the following files:

• an index.rst file explaining the example
• an exXXX.sh script file
• necessary and small data files [optional]

In this PR, I add a demo example "ex001" to show how the new page works. The generated image (ex001.ps) is not included, because

1. Adding hundreds of PS files increases the repository size quickly
2. These simple examples should always work, and should be already covered by existing tests. I don't think we should add them to the GMT tests.
3. The generated PNG image is uploaded to github (by dragging the image to any issue comment), and the github image link should be valid for a very long time.

Preview: https://gmt-git-example-page-gmt.vercel.app/examples/index.html

[seisman]

Ping @PaulWessel @joa-quim @meghanrjones @Esteban82 @KristofKoch for comments

[PaulWessel]

This is great, @seisman! I have a few comments and suggestions:

I agree this should focus on very simple things to demonstrate them. Might there be separate categories or groups we want to keep separate? I am thinking

• Basemaps (various basemap examples)
• Coastlines (various coast examples)
• symbols (various plot -S examples)
• lines/polygons (various plot examples)
• grid images (grdimage, grdview)
• contour maps (grdcontour, pscontour)

Maybe others? I think just having a hodge-podge of examples will be frustrating.

[seisman]

I agree this should focus on very simple things to demonstrate them. Might there be separate categories or groups we want to keep separate? I am thinking

• Basemaps (various basemap examples)
• Coastlines (various coast examples)
• symbols (various plot -S examples)
• lines/polygons (various plot examples)
• grid images (grdimage, grdview)
• contour maps (grdcontour, pscontour)

Maybe others? I think just having a hodge-podge of examples will be frustrating.

Yes, similar categories are being used in the PyGMT Gallery and we can also do that in the GMT side.

The index.rst is very flexible and can include any figures in any categories. We can even include images that are already in the cookbook.

Edit: More categories are added in commit 8848c52.

[anbj]

This is an excellent idea!

• Any maximum number of script lines? How simple is simple?
• A script may be catagorized in multiple ways, which take precedence?
• Is it allowed to use other tools, e.g. gdal?
• Should the threshold be low for creating an example?
  • Simply, "look, I made this" or
  • "I bet other people are struggling with this as well, better create an example"?
• Modern mode, classic mode or both?

[joa-quim]

We have talked about this many times. I think we should aim to mimic the example types like the Matplotlib example pages. Don't think the main goal here is to have very simple plots, but to have simple scripts (as much as they can be) to produce practical figs. xy, bars, histograms, images, etc...

[seisman]

I think we should aim to mimic the example types like the Matplotlib example pages. Don't think the main goal here is to have very simple plots, but to have simple scripts (as much as they can be) to produce practical figs. xy, bars, histograms, images, etc...

Yes, I agree.

• Any maximum number of script lines? How simple is simple?

As mentioned by @joa-quim, the scripts should be as simple as possible. Some simple but practical examples can be found at the PyGMT Gallery, the GMT.jl Gallery and Matplotlib Gallery. We can even create some examples from the PyGMT or GMT.jl gallery, so that users can know how to plot the same plot using GMT CLI, PyGMT or GMT.jl.

• Is it allowed to use other tools, e.g. gdal?

Yes, any command-line tools should be allowed, but a note should be added to make it clear that external commands are needed.

• Modern mode, classic mode or both?

I would prefer the modern mode only. Mixing modern and classic modes in the examples would make users more confusing.

[joa-quim]

Remember that all GMT.jl scripts when using the Vd=1 option will print the generated GMT command that can be run directly (plus the input data file name).

[KristofKoch]

I like it @seisman – but where to draw the line? Currently the docs for each program have that example section at the end with mostly one-liner examples but without the resulting plots. This might be a good starting point? I feel it is a bit difficult to separate the examples properly. We got some examples in the man pages, some in the cookbook and some on the current examples page.

I think we can all agree that the learning curve for the finer points is still rather steep. So to quote @anbj:

"look, I made this"

would be the best approach in my eyes. Maybe even multiple examples for different options. -B comes to mind.

[maxrjones]

The matplotlib gallery includes a showcase section, which seems analogous to the current GMT example gallery section and also an "I made this" section. I think that the other sections should be about simple scripts that demonstrate how to accomplish a single, practical goal using GMT (but may leverage other tools), similar to Joaquim's suggestion.

[joa-quim]

Between GMT.jl and PyGMT we already have quite a few of those basic but useful examples. We could gather those that are common, or can be easily implemented in the other wrapper, in a common group. Then each image would have 3 links pointing to the languages in which they can be written.

[anbj]

One more question:

Should the examples be fully self contained? That is, should the code always produce a (finalized) figure?

I can think of a couple of cases where a proof-of-concept is enough/the point per se. E.g.

gmt grdcontour [this is where the magic happens] -K -O >> $ps

[anbj]

And yet more:

How does this new section relate to the existing https://docs.generic-mapping-tools.org/latest/users-contrib-scripts.html?

[Esteban82]

Great idea. It would be possible to add labels (like here or the keyword in a paper) for each example? I think that it would help the users. Also some scripts from the test folder could be add.

[maxrjones]

And yet more:

How does this new section relate to the existing https://docs.generic-mapping-tools.org/latest/users-contrib-scripts.html?

This section seems the same to me as the showcase on the forum. Could we consolidate?

[seisman]

Sorry for forgetting this PR for months.

but where to draw the line? Currently the docs for each program have that example section at the end with mostly one-liner examples but without the resulting plots. This might be a good starting point? I feel it is a bit difficult to separate the examples properly. We got some examples in the man pages, some in the cookbook and some on the current examples page.

The index.rst page is quite flexible, so it's even possible to include existing figures in anywhere. For example, we can add histogram plots in the example section of the histogram man page, and also directly show them in the new example gallery.

Should the examples be fully self contained? That is, should the code always produce a (finalized) figure?

I can think of a couple of cases where a proof-of-concept is enough/the point per se. E.g.

gmt grdcontour [this is where the magic happens] -K -O >> $ps

I think the examples should be fully self contained so that users can copy the script, run it and then modify it. Without a final figure, people may have to read a long paragraph to understand what the example does and what the magic is.

How does this new section relate to the existing docs.generic-mapping-tools.org/latest/users-contrib-scripts.html?

I think the section is here for some historic reasons, but since there is only one script, we may move it to here.

It would be possible to add labels (like here or the keyword in a paper) for each example? I think that it would help the users.

It's definitely possible to add labels or keywords. It would be better if we can filter examples by lables/keywords, but it's challenging for me (need more knowledge about javascript and other web knowledge),

Also some scripts from the test folder could be add.

Yes, but we may have to duplicate the scripts because the doc directory may not be able to access the test directory.

This section seems the same to me as the showcase on the forum. Could we consolidate?

We can also show the examples posted in the forum and add links to them.

[Esteban82]

Maybe this could be talk is next community meeting?

[maxrjones]

Maybe this could be talk is next community meeting?

Sounds good, I will add this to the agenda.

[maxrjones]

I do not think we should use this strategy for including images hosted on GitHub because anyone who builds the documentation and/or uses the bundle docs offline will not be able to see the images.

[maxrjones]

Given that there will likely be many small, practical examples (in addition to new tutorial pages depending on funding) and that we want to leverage community contributions for these pages, I think we should consider hosting the examples in a separate repository. Here are my primary reasons:

1. Needing to first build GMT in order to build the documentation is a barrier for new contributors. The API docs need to be in the same repository as the source code so that we can easily bundle for distribution. I do not see this same need for teaching-based materials (e.g., how-to guides and tutorials). If it were in a separate repository, we could add a conda environment file so that the only instructions people need are:

   conda env create -f environment.yml
   conda activate gmt-examples
   cd site
   make html
   

   which is quite simple compared to the current steps required in building.md and maintenance.md.

2. We are limited in the tools that we can use for the examples/tutorials because all the extensions for building the core GMT docs need to be included in the repository (e.g., Use MyST parser for changelog and contributing documentation #5542). If we were to host the simple examples/tutorials in a separate repo, we could use tools like MyST-NB to support Jupyter notebook-based examples, which could be launched in Binder and are much simpler for new contributors than the current ReST structure. This is just one example of an external tool that could help the pages.

3. As we grow the team, there may be people who are only interested in either contributing code or documentation. If we have a separate repository for the simple how-to-guides/tutorials, it would make it so that people who are purely interested in coding developments do not need to clone/watch all the teaching pages and vice versa.

[gd-a]

What's the status of this PR ? Do we have a list of examples that need to be done ?

[seisman]

Sorry again for forgetting this PR.

I agree with @meghanrjones's 3 points that a separate repository is a better option for GMT examples. So, As I understand it, what we should do is:

1. Create a separate repository (e.g., gmt-examples) to host examples
2. Create a new site from the new repository. The site domain can be
   • gallery.generic-mapping-tools.org
   • showcase.generic-mapping-tools.org
   • examples.generic-mapping-tools.org
3. After the new site is live, we should add the link to the sidebar of the docs.generic-mapping-tools.org site

My question is: do we still want to use dvc to manage these example images as mentioned in #5724 or do we just upload these static images to GitHub?

[maxrjones]

Sorry again for forgetting this PR.

I agree with @meghanrjones's 3 points that a separate repository is a better option for GMT examples. So, As I understand it, what we should do is:

1. Create a separate repository (e.g., `gmt-examples`) to host examples

2. Create a new site from the new repository. The site domain can be
   
   * `gallery.generic-mapping-tools.org`
   * `showcase.generic-mapping-tools.org`
   * `examples.generic-mapping-tools.org`

3. After the new site is live, we should add the link to the sidebar of the `docs.generic-mapping-tools.org` site

My question is: do we still want to use dvc to manage these example images as mentioned in #5724 or do we just upload these static images to GitHub?

Sorry for leaving this PR without a response for so long. Since we aren't using these examples as tests, I think we can use the sphinx_gmt extension to generate the images when building the docs rather than storing the static images on GitHub or DAGsHub. Do you mind if I create the gmt-examples repository and open a PR with a potential structure using some of the executable books extensions and the sphinx_gmt extension?

[maxrjones]

I'll get started on the gmt-examples repository today unless there are any objections, since it would be particularly helpful to put in some examples for vector attributes.