Add figures to examples of the docs

[Esteban82]

In the section examples of the modules docs, I think we can add the figure generated by each example. I think it would help to understand them and also would make the docs more friendly-user (at least for me).

For example in the mask docs it says:

gmt begin mask
  gmt math -T-90/90/10 -N2/1 0 = | gmt mask -Gyellow -I30m -R-75/75/-90/90 -JQ0/7i \
    -S5d -T -Bafg10 -BWSne+t"Mask for points with r = 5 degrees"
gmt end show

and we could add the figure generated by these commands:

Are you willing to help making the figures and add them in the docs? Yes. Also maybe Meghan could do it?

[seisman]

To add one example image to the documentation, we need to add the script and the PS file in the doc/scripts directory. See that directory for other examples.

---

Besides that, I'd like to draw your attention to the sphinx extension sphinx_gmt developed by @leouieda and me a few years ago. With this extension, we can write GMT commands/scripts in the reST source files. When building the documentation, sphinx will run the scripts, generate the images, and insert the codes and images into the HTML documentation.

Here is an example. We can write the following script in the reST source file (gmtplot is the reST directive provided by sphinx_gmt):

and the HTML documentation will look like:

The sphinx_gmt extension supports any GMT versions, both classic and modern modes, and both bash and PyGMT scripts. Its full documentation is available at https://www.generic-mapping-tools.org/sphinx_gmt/latest/. FYI, this extension is being used in the Chinese GMT documentation (https://docs.gmt-china.org/latest/), and all images you see on that site are generated by sphinx_gmt.

Here are some pros and cons of using sphinx_gmt in the GMT documentation:

Pros:

1. Easier to insert images into documentation
2. No need to add the scripts and PS files into the repository, thus keep the repository size small
3. No need to add the scripts as GMT's tests, thus keep the number of GMT's tests (now it's ~900) small

Cons:

1. Building the documentation will be slower than before, because all the images are generated during the documentation building. [For your reference, the Chinese GMT documentation has ~200 simple images, and building the documentation takes ~3 minutes. So not bad to me.].
2. These scripts won't be added into the GMT's tests so they are not tested. Thus, the images may be incorrect if the commands are wrong.

[Esteban82]

Thanks Dongdong. I didn't knew sphinx_gmt. Great job.

Maybe I was not clear. Should I proceed to add the figures in the docs? Or there is a good reason not do it?

[seisman]

I'm guessing that @PaulWessel and @joa-quim may be unaware of the sphinx_gmt extension.

Should I proceed to add the figures in the docs?

Of course, you can. I just want to take the opportunity to have more discussions about how to add example images into the documentation. Apparently, there are two different ways to do that:

1. the classic way: add the scripts and images to the doc/scripts directory
2. the "modern" way: use the sphinx_gmt extension.

Each way has its pros and cons (see my previous comment). I prefer the "modern" way, but let's hear what @PaulWessel, @joa-quim, and other contributors think.

[leouieda]

This is a bit of a trade-off between convenience and testing. It's much easier to add examples to the docs using the sphinx extension. But GMT relies a lot of the documentation plots as tests (which is why devs were hesitant to move entirely to sphinx_gmt when I suggested). I can see a few ways forward:

1. Go with sphinx_gmt: pro = lower barrier for docs contributions (which we greatly need) | con = reduced tests (could be mitigated by moving scripts from docs to tests)
2. Stay with the current setup: pro = nothing to be done | con = much harder to ask people to contribute to the docs
3. Use a mix of both: pro = not much work to be done updating existing plots | con = difficult to explain to new contributors
4. Build testing into sphinx_gmt so we can optionally compare images (with pytest-mpl?): pro = simpler doc building + testing of plots | con = will take some work upfront to implement the capability

Personally, I lean towards option 4 or 1. I think the benefits of lowering barriers to contribution in the docs vastly out weights the benefits of testing the docs scripts.

[Esteban82]

Maybe this could be discussed in the next Thursday in the community meeting.

[PaulWessel]

Yep, agreed.

[stale[bot]]

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.