Add inline code examples in plotting module docstrings

GenericMappingTools / pygmt

A Python interface for the Generic Mapping Tools.

https://www.pygmt.org

BSD 3-Clause "New" or "Revised" License

758 stars 220 forks source link

Add inline code examples in plotting module docstrings #1957

Open willschlitzer opened 2 years ago

willschlitzer commented 2 years ago

As mentioned in this comment, this is a checklist to add inline code examples in the plotting module docstrings.

[ ] basemap
[x] coast (#2142)
[ ] colorbar (#2373)
[ ] contour
[x] grd2cpt (#2145)
[x] grdcontour (#2148)
[x] grdimage (#2146)
[ ] grdview (#2381)
[ ] histogram
[ ] image
[ ] inset
[ ] legend
[ ] logo
[ ] makecpt
[ ] meca
[ ] plot
[ ] plot3d
[ ] rose
[x] solar (#2147)
[ ] text
[ ] velo
[ ] wiggle

Are you willing to help implement and maintain this feature? Yes

seisman commented 2 years ago

Hmmm, do we really need to add inline examples for these plotting modules?

Looking at the inset documentation, I think the visual examples at the bottom are more useful than the code example.

willschlitzer commented 2 years ago

I thought the general attitude was that inline examples should still be added to plotting modules. My thought it that working code is provided on the function's page without the need to click around to other examples.

@meghanrjones @weiji14 Thoughts?

weiji14 commented 2 years ago

The visual examples at the bottom are indeed more useful, but I think it's worth having an example in the docstring as well (e.g. for people working offline). That said, definitely lower on the priority list for now, something for PyGMT v0.8.0 or v0.9.0.