Missing Examples for user facing function

[jbusecke]

Description of the desired feature

First of all, the existing examples are really, really nice! They helped me a lot understanding the functionality.

I was however not able to find examples for pygmt.Figure.psconvert, pygmt.Figure.grd2cpt, and pygmt.set_display.

Furthermore many of the processing functions are not show in the examples as far as I can tell.

[weiji14]

First of all, the existing examples are really, really nice! They helped me a lot understanding the functionality.

Thanks for the kind words, glad you found them helpful :smiley:

I was however not able to find examples for pygmt.Figure.psconvert, pygmt.Figure.grd2cpt, and pygmt.set_display.

Agree that pygmt.grd2cpt should have a gallery example, there's 7 for pygmt.makecpt at https://www.pygmt.org/v0.5.0/api/generated/pygmt.makecpt.html#examples-using-pygmt-makecpt so we could maybe change 1 or 2 over.

As for pygmt.Figure.psconvert and pygmt.set_display, these functions are mostly for advanced users. We could perhaps add an inline usage docstring for these, similar to that at https://www.pygmt.org/v0.5.0/api/generated/pygmt.config.html.

Furthermore many of the processing functions are not show in the examples as far as I can tell.

Yes you are correct that most data processing functions don't have examples. The main reason is probably because we don't want to slow down the Docs Build CI which currently takes 15 minutes. Bearing in mind that a data processing gallery example would need to 1) run the data processing and 2) produce a plot, which is quite a lot, but definitely possible (there's a recent one @michaelgrund made at https://github.com/GenericMappingTools/pygmt/pull/1598).

Action point: I think inline docstring might be the way to go with some of these examples. Upstream GMT has done this (e.g. at https://docs.generic-mapping-tools.org/6.3/basemap.html#examples), so we can probably translate these to PyGMT. The pygmt.grdfilter function has an example we can use as a reference. Key challenge might be to prevent these inline code examples from running in CI (but definitely check that the syntax is ok).

[willschlitzer]

Action point: I think inline docstring might be the way to go with some of these examples. Upstream GMT has done this (e.g. at https://docs.generic-mapping-tools.org/6.3/basemap.html#examples), so we can probably translate these to PyGMT. The pygmt.grdfilter function has an example we can use as a reference. Key challenge might be to prevent these inline code examples from running in CI (but definitely check that the syntax is ok).

I agree with using inline examples. I use the GMT inline examples to demonstrate the syntax for non-plotting modules when writing the tests for module-wrapping.

[willschlitzer]

@GenericMappingTools/pygmt-maintainers Would it be a good idea to add inline docstring examples (without an associated plot) to all of our module docstrings? That way the page would be a one-stop-shop without needing to go to an example.

[maxrjones]

@GenericMappingTools/pygmt-maintainers Would it be a good idea to add inline docstring examples (without an associated plot) to all of our module docstrings? That way the page would be a one-stop-shop without needing to go to an example.

Yes to me, as long as we can skip the inline examples in the CI and locally when needed.