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

Figure.coast: Add alias "box" for "-F" #2823

Merged
merged 11 commits into from
Dec 8, 2023
Merged

Figure.coast: Add alias "box" for "-F" #2823

Changes from 9 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
030b7a6
Add alias 'box' for '-F' to list and copy-past docstring from basemap
yvonnefroehlich Nov 19, 2023
1d650bb
Merge branch 'main' into add-coast-alias-F
yvonnefroehlich Nov 20, 2023
5084862
Merge branch 'main' into add-coast-alias-F
yvonnefroehlich Nov 26, 2023
a32e08a
Sort alias list alphetically
yvonnefroehlich Nov 26, 2023
824ea17
Merge branch 'main' into add-coast-alias-F
yvonnefroehlich Nov 30, 2023
417ed69
Merge branch 'main' into add-coast-alias-F
yvonnefroehlich Dec 1, 2023
d0d904c
Merge branch 'main' into add-coast-alias-F
yvonnefroehlich Dec 3, 2023
6c2be0d
Merge branch 'main' into add-coast-alias-F
yvonnefroehlich Dec 5, 2023
f85470e
Merge branch 'main' into add-coast-alias-F
yvonnefroehlich Dec 7, 2023
9be73a9
Use plural for clearances of box parameter
Dec 8, 2023
02fbadc
Revert "Use plural for clearances of box parameter"
Dec 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 24 additions & 5 deletions pygmt/src/coast.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,20 +17,21 @@

@fmt_docstring
@use_alias(
R="region",
J="projection",
A="area_thresh",
C="lakes",
B="frame",
C="lakes",
D="resolution",
E="dcw",
F="box",
G="land",
I="rivers",
J="projection",
L="map_scale",
N="borders",
W="shorelines",
G="land",
R="region",
S="water",
V="verbose",
W="shorelines",
c="panel",
p="perspective",
t="transparency",
Expand Down Expand Up @@ -128,6 +129,24 @@ def coast(self, **kwargs):
[**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
**+w**\ *length*.
Draw a simple map scale centered on the reference point specified.
box : bool or str
[**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
[**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
If set to ``True``, draw a rectangular border around the
map scale or rose. Alternatively, specify a different pen with
**+p**\ *pen*. Add **+g**\ *fill* to fill the scale panel [Default is
no fill]. Append **+c**\ *clearance* where *clearance* is either gap,
xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform,
separate in x- and y-direction, or individual side spacings between
scale and border. Append **+i** to draw a secondary, inner border as
Comment on lines +132 to +141
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the function string we have (plural)

[**+c**\ *clearances*]

but in the docstring we write (singular):

**+c**\ *clearance*

This is also the case in the upstream GMT documentation, as there is made a difference between "a uniform clearance" and "separate / individual clearances" (please see https://docs.generic-mapping-tools.org/dev/coast.html#f). But in the PyGMT docstring we do not have these terms, and maybe we should use either singular or plural, even it is not consistent with the GMT docs?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using plural makes more sense to me.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to "clearances" (plural) for Figure.basemap and Figure.coast in commit 9be73a9.

But there are actually more affected docstrings. Maybe we should move this change to a separate PR and focus in this PR on adding the alias box for -F?

(base) yfroe@gpiseis16:~/Documents/01_GitHub/github_pygmt/pygmt/pygmt/src> grep "clearance" *
basemap.py:        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
basemap.py:        no fill]. Append **+c**\ *clearance* where *clearance* is either gap,
colorbar.py:        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
colorbar.py:        **+c**\ *clearance* where *clearance* is either gap, xgap/ygap, or
image.py:        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
inset.py:        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\
inset.py:        Append **+c**\ *clearance* where *clearance* is either
inset.py:        This is clearance that is added around the inside of the inset.
legend.py:        [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
grep: __pycache__: Is a directory
subplot.py:    C="clearance",
subplot.py:        **+c**\ *dx*\[/*dy*] to set the clearance between the tag and a
subplot.py:    clearance : str or list
subplot.py:        [*side*]\ *clearance*.
subplot.py:        Reserve a space of dimension *clearance* between the margin and the
subplot.py:        **s** and **n**. No *side* means all sides (i.e. ``clearance="1c"``
subplot.py:        would set a clearance of 1 cm on all sides). The option is repeatable
subplot.py:        ``clearance=["w1c", "s2c"]`` would set a clearance of 1 cm on west
subplot.py:        ``clearance`` to secure extra space for long horizontal annotations.
subplot.py:@use_alias(A="fixedlabel", C="clearance", V="verbose")
subplot.py:    clearance : str or list
subplot.py:        [*side*]\ *clearance*.
subplot.py:        Reserve a space of dimension *clearance* between the margin and the
subplot.py:        than one side (e.g. ``clearance=["w1c", "s2c"]`` would set a clearance
subplot.py:        clearances set by ``clearance`` in the initial
text.py:    C="clearance",
text.py:    clearance : str
text.py:        Adjust the clearance between the text and the surrounding box
text.py:        (see ``clearance``) [Default is ``"0.25p,black,solid"``].

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel these are just minor issues and aren't worth the time fixing them. On the other hand, it's likely that we need to fully revise these docstrings towards a Pythonic interface (#1082 (comment)).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK. Then we leave this as is and this PR should be finished. I revert commit 9be73a9.

well. We use a uniform gap between borders of 2p and the
:gmt-term:`MAP_DEFAULTS_PEN` unless other values are specified. Append
**+r** to draw rounded rectangular borders instead, with a 6p corner
radius. You can override this radius by appending another value.
Finally, append **+s** to draw an offset background shaded region.
Here, *dx/dy* indicates the shift relative to the foreground frame
[Default is ``"4p/-4p"``] and shade sets the fill style to use for
shading [Default is ``"gray50"``].
borders : int, str, or list
*border*\ [/*pen*].
Draw political boundaries. Specify the type of boundary and
Expand Down