Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Missing Examples for user facing function #1666

Open
jbusecke opened this issue Dec 14, 2021 · 4 comments
Open

Missing Examples for user facing function #1666

jbusecke opened this issue Dec 14, 2021 · 4 comments
Labels
documentation Improvements or additions to documentation help wanted Helping hands are appreciated

Comments

@jbusecke
Copy link
Contributor

jbusecke commented Dec 14, 2021

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.

@jbusecke jbusecke added the feature request New feature wanted label Dec 14, 2021
@weiji14 weiji14 added documentation Improvements or additions to documentation and removed feature request New feature wanted labels Dec 14, 2021
@weiji14
Copy link
Member

weiji14 commented Dec 14, 2021

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 😃

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 #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
Copy link
Contributor

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
Copy link
Contributor

@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
Copy link
Member

@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.

@weiji14 weiji14 added this to the 0.6.0 milestone Jan 8, 2022
@weiji14 weiji14 pinned this issue Jan 14, 2022
@weiji14 weiji14 added the help wanted Helping hands are appreciated label Mar 10, 2022
@weiji14 weiji14 modified the milestones: 0.6.0, 0.6.1 Mar 11, 2022
@weiji14 weiji14 unpinned this issue Mar 21, 2022
@seisman seisman modified the milestones: 0.6.1, 0.7.0 Apr 9, 2022
@seisman seisman modified the milestones: 0.7.0, 0.8.0 Jun 23, 2022
@seisman seisman modified the milestones: 0.8.0, 0.9.0 Dec 11, 2022
@seisman seisman modified the milestones: 0.9.0, 0.10.0 Mar 19, 2023
@weiji14 weiji14 modified the milestones: 0.10.0, 0.11.0 Aug 29, 2023
@seisman seisman modified the milestones: 0.11.0, 0.12.0 Dec 11, 2023
@seisman seisman removed this from the 0.12.0 milestone Feb 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation help wanted Helping hands are appreciated
Projects
None yet
Development

No branches or pull requests

5 participants