Update the docstrings in the plotting modules

[maxrjones]

Description of proposed changes

Update the docstrings of aliases following the convention in #631.

To do:

• Update docstrings for data modules
• Format docstrings as raw strings

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[maxrjones]

I'm not sure how to mark this PR as 'draft' (edit: nevermind, found it). Currently done with the plotting modules and will update the data processing modules tomorrow.

[weiji14]

Wow, you're fast!

Currently done with the plotting modules and will update the data processing modules tomorrow.

To keep things small (and easier to review, see https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md#general-guidelines), you can split it into 2 PRs, 1 for plotting modules (this PR), 1 for data processing modules. Just ask @willschlitzer to review if you think it's ready, I think he'll be keen and it's his ideal timezone now too.

[maxrjones]

To keep things small (and easier to review, see https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md#general-guidelines), you can split it into 2 PRs, 1 for plotting modules (this PR), 1 for data processing modules. Just ask @willschlitzer to review if you think it's ready, I think he'll be keen and it's his ideal timezone now too.

Sounds good. grd2cpt, makecpt, savefig, show, and psconvert also remain but those could similarly go in a different PR to keep things small. Also based on that recommendation, it seems that it's probably fine that this PR really just covers the simplest cases. An example of a more complex situation is meca, in which the arguments do not map simply to GMT options.

[maxrjones]

Many of the arguments refer to other arguments, for example lakes from coast refers to water:

lakes : str or list
fill\ [+l|\ +r].
Set the shade, color, or pattern for lakes and river-lakes. The
default is the fill chosen for wet areas set by the water
argument. Optionally, specify separate fills by appending
+l for lakes or +r for river-lakes, and passing multiple
strings in a list.

Most of the references to other arguments are formatted in a code block, should this be kept or changed to bold similar to cross-references in gmt?

[seisman]

Many of the arguments refer to other arguments, for example lakes from coast refers to water:

lakes : str or list
fill\ [+l|\ +r].
Set the shade, color, or pattern for lakes and river-lakes. The
default is the fill chosen for wet areas set by the water
argument. Optionally, specify separate fills by appending
+l for lakes or +r for river-lakes, and passing multiple
strings in a list.

Most of the references to other arguments are formatted in a code block, should this be kept or changed to bold similar to cross-references in gmt?

IMHO, we should try our best to document the arguments of PyGMT modules, rather than refering users to read the GMT documentation. That's why I prefer to use code blocks for PyGMT arguments.

[willschlitzer]

Nice work!

[willschlitzer]

Wow, you're fast!

Currently done with the plotting modules and will update the data processing modules tomorrow.

To keep things small (and easier to review, see https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md#general-guidelines), you can split it into 2 PRs, 1 for plotting modules (this PR), 1 for data processing modules. Just ask @willschlitzer to review if you think it's ready, I think he'll be keen and it's his ideal timezone now too.

@meghanrjones I changed this PR to just be for plotting functions and I'm about to tackle the non-plotting functions. I looked through your fork's branches and it looks like you haven't started on that.

[seisman]

Perhaps we can just ignore my last-minute suggestions and merge this PR as it is? @weiji14

[weiji14]

Perhaps we can just ignore my last-minute suggestions and merge this PR as it is? @weiji14

They seem to be fair suggestions, should be ok to just batch commit them before merging.

[seisman]

I can't do the batch commit, possibly because this PR comes from @meghanrjones's own fork.

[weiji14]

I can't do the batch commit, possibly because this PR comes from @meghanrjones's own fork.

Ah I see. Let's just merge it then (and apply the changes in another small PR?) since it's a public holiday in the US. And we should add her to the PyGMT team so she can create branches on GenericMappingTools/pygmt next time.

[seisman]

Let's just merge it then.

Great!

apply the changes in another small PR?

I'm heading to the grocery. Feel free to many small changes in PRs.

And we should add her to the PyGMT team so she can create branches on GenericMappingTools/pygmt next time.

She is already in the python team.

[weiji14]

Ah ok, must have missed one of the messages. I'll merge this in in a bit.

[maxrjones]

Should I batch commit them now?

[weiji14]

Oh hi @meghanrjones! Sorry for bothering you on a weekend/public holiday. Yes go ahead please!

[willschlitzer]

Should I batch commit them now?

Please do (assuming you agree with the proposed changes)!

[weiji14]

/format

And also, could you click on the 'Update branch' button (or check the 'Allow updates from maintainers' box so we can update it for you). Thanks.

[maxrjones]

I can create branches from GenericMappingTools in the future if that's preferred. Sorry, I didn't want to make any assumptions when setting up this branch.

[weiji14]

I can create branches from GenericMappingTools in the future if that's preferred. Sorry, I didn't want to make any assumptions when setting up this branch.

Yes please! I realize that this probably needs to be in CONTRIBUTING.md (create branches on GenericMappingTools) since Will was doing branches on his own fork for a while too.

And sorry for all the haste, just that we really want to finish that v0.3.0 milestone (but that shouldn't come at the expense of people's lives, not everyone is or should be a workaholic).

[maxrjones]

I can create branches from GenericMappingTools in the future if that's preferred. Sorry, I didn't want to make any assumptions when setting up this branch.

Yes please! I realize that this probably needs to be in CONTRIBUTING.md (create branches on GenericMappingTools) since Will was doing branches on his own fork for a while too.

And sorry for all the haste, just that we really want to finish that v0.3.0 milestone (but that shouldn't come at the expense of people's lives, not everyone is or should be a workaholic).

No problem, I'll be free for the next half hour or so and if this extends beyond that then I'll click the box for you all to be able to finish it up.

[maxrjones]

There was an unescaped return in decorators.py that was causing a space in the perspective arguments. I added a fix to this PR, but feel free to change it back if needed. I won't be able to look at this again today, so feel free to commit new suggestions as needed @weiji14, @willschlitzer, and @seisman.

[weiji14]

All this attention to detail! Alright, merging this now.