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.

Sign up for GitHub

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

Jump to bottom

Add a gallery example for Figure.legend with StringIO input #3444

Open
seisman opened this issue Sep 18, 2024 · 4 comments · May be fixed by #3594
Open

Add a gallery example for Figure.legend with StringIO input #3444

seisman opened this issue Sep 18, 2024 · 4 comments · May be fixed by #3594
Labels
documentation Improvements or additions to documentation help wanted Helping hands are appreciated

Comments

@seisman
Copy link
Member

seisman commented Sep 18, 2024 •
edited
Loading

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 #3438.
@seisman seisman added documentation Improvements or additions to documentation help wanted Helping hands are appreciated labels Sep 18, 2024
@weiji14 weiji14 mentioned this issue Sep 19, 2024
Closed
@yvonnefroehlich
Copy link
Member

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

seisman commented Sep 21, 2024

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

@yvonnefroehlich
Copy link
Member

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

seisman commented Sep 23, 2024

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 #3438 is qualified as a good gallery example.

@yvonnefroehlich yvonnefroehlich linked a pull request Nov 6, 2024 that will close this issue
Draft
11 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation help wanted Helping hands are appreciated
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

WIP: DOC: Add advanced tutorial "Creating legends" GenericMappingTools/pygmt
2 participants
@seisman @yvonnefroehlich