Document how to parse verbose messages to report equivalent GMT commands

[seisman]

Description of the desired feature

Sometimes we may need the equivalent GMT commands. For example,

1. some PyGMT issues are actually due to upstream GMT bugs (https://forum.generic-mapping-tools.org/t/829). When we open a GMT bug, we need the equivalent bash script
2. currently, how PyGMT works is a little fragile. Any unknown arguments are directly passed to GMT. See a bug report #256. The error messages are really confusing. But if the equivalent CLI commands are printed out, it would be much easier to understand why it doesn't work as expected.

GMT already provides 7 verbosity levels by the -V option. The 7 verbosity levels (higher levels add more messages) are:

q < e < w < t < i < c < d

Here I propose to add one more verbosity level, for example, verbose='p'. The verbosity level should be between q and e, i.e.,

q <   < e < w < t < i < c < d
    ^
    |
    p

If verbose='p' is used, they PyGMT should print the equivalent GMT command when calling the function call_module().

I only spent a few seconds to choose the character p and its verbosity level. So I'm open to better choices.

Are you willing to help implement and maintain this feature?

Yes, it should be easy to implement it in the call_module() function. Contributions are welcomed.

[weiji14]

I think the intention is good, it does take a bit of experience translating PyGMT Python commands to GMT bash commands, and any way we can simplify this to improve bug reports will be a plus.

That said, I'm not sure if this should live in the PyGMT library. Presumably other GMT wrappers like GMT.jl and GMTmex might find it useful too?

[seisman]

Ping @PaulWessel @joa-quim for thoughts on this.

[PaulWessel]

First reaction is that it sounds like a debug option, hence might be part of -Vd, but I am guessing you want to just see those commands. Of course, it makes no sense from the command line GMT to document and explain p since we already have the commands. So, first to check, might this go into -Vd as is?

[weiji14]

How about just for -Vi at the informative level?

[PaulWessel]

Sure, and actually, we know if we are called from externals (API->external is true) so we could print command when it makes sense.

[seisman]

For cross-reference, the feature will be implemented in upstream GMT https://github.com/GenericMappingTools/gmt/pull/4131.

[seisman]

The feature has been implemented in the GMT master branch. Here is an example showing how it works:

The example PyGMT script

#!/usr/bin/env python
import pygmt

### To report equivalent GMT commands, you need to add this line to your PyGMT script
pygmt.config(GMT_VERBOSE='d')

fig = pygmt.Figure()
fig.basemap(region='g', projection='H15c', frame=['xaf', 'yaf', '+t"Global Map"'])
fig.coast(shorelines='1/0.5p')
fig.savefig("map.pdf")

Then, run the script and extract the GMT commands from verbose messages:

$ python test.py 2>&1 | grep GMT_Call_Command | awk -F': ' '{print "gmt", $3}'

gmt figure 71485df0ed3b4d4983d7a2d6bc2a5445 -
gmt figure 71485df0ed3b4d4983d7a2d6bc2a5445 -
gmt basemap -Bxaf -Byaf -B+t"Global Map" -JH15c -Rg
gmt figure 71485df0ed3b4d4983d7a2d6bc2a5445 -
gmt coast -W1/0.5p
gmt figure 71485df0ed3b4d4983d7a2d6bc2a5445 -
gmt psconvert -A -Fmap -Qg2 -Qt2 -Tf
gmt end
gmt figure 71485df0ed3b4d4983d7a2d6bc2a5445

[seisman]

Shall we document it somewhere?

[weiji14]

Yep, should document this in CONTRIBUTING.md or perhaps in our bug report template? Might need to wait for GMT 6.2.0 to come out near the end of the year though.

[seisman]

perhaps in our bug report template

I don't think users need to know the trick when reporting bugs. Perhaps better to document it in CONTRIBUTING.md.