Add a gallery example for Figure.legend with StringIO input

[seisman]

We already use the auto-legend feature in some tutorials/gallery examples, but we don't have an example for how to manually specify the legend specification. This gallery example (https://www.pygmt.org/dev/gallery/embellishments/legend.html) provides a link to the GMT official documentation and mentions that Figure.legend can accept a legend specification file without details.

After #3438 is merged, it would be possible to store the legend specification in a StringIO object, so an example would be good.

I think we can add the GMT official example at https://docs.generic-mapping-tools.org/6.5/legend.html#examples as a PyGMT gallery example, similar to the test in https://github.com/GenericMappingTools/pygmt/pull/3438.

[yvonnefroehlich]

The StringIO input option is a nice addition to the legend method.

Should such a gallery example also explain the (main) GMT legend codes (see https://docs.generic-mapping-tools.org/6.5/legend.html#legend-codes)? I feel, for the mentioned GMT example, some addional comments are needed, as understanding a GMT legend specification file requires some knowledge of the GMT syntax (: .

[seisman]

perhaps we should have a tutorial for legend rather than a gallery example.

[yvonnefroehlich]

perhaps we should have a tutorial for legend rather than a gallery example.

Hm, should such a tutorial focus on creating a legend manually (including the main GMT legend codes) or covering both auto-legends (including the main modifiers that can be appended to the label parameter to adjust the legend) and manual legends (stringIO input, GMT legend codes)? For the later case, would this mean that we remove the current legend example or include it in this new tutorial? Maybe it is still good to have a short example showing how to add a legend in principle.

[seisman]

Should such a gallery example also explain the (main) GMT legend codes (see https://docs.generic-mapping-tools.org/6.5/legend.html#legend-codes)? I feel, for the mentioned GMT example, some addional comments are needed, as understanding a GMT legend specification file requires some knowledge of the GMT syntax (: .

We should not explain too many details about the legend codes in either a gallery example or a tutorial. These details should be written in the API documentation of Figure.legend.

Hm, should such a tutorial focus on creating a legend manually (including the main GMT legend codes) or covering both auto-legends (including the main modifiers that can be appended to the label parameter to adjust the legend) and manual legends (stringIO input, GMT legend codes)? For the later case, would this mean that we remove the current legend example or include it in this new tutorial? Maybe it is still good to have a short example showing how to add a legend in principle.

I think we have both a tutorial and multiple gallery examples. The tutorial should include topics like:

• how to use auto legend
• how to add legend manually by giving a legend specification file or a StringIO object
• how to specify the legend position on map
• how to add the legend box

The gallery example should show what Figure.legend can do (e.g., two columns legend with lines, symbols, texts, colorbar/scalebar). That's why I think the complicated example in https://github.com/GenericMappingTools/pygmt/pull/3438 is qualified as a good gallery example.