How to reproduce original GMT arguments in PyGMT documentation

[weiji14]

Description of the desired feature

The GMT documentation has many instances where bold and italicized fonts are mixed, looking something like:

+nargs

The PyGMT documentation has been rather inconsistent with this (see mentions at https://github.com/GenericMappingTools/pygmt/pull/525#discussion_r454414687 and https://github.com/GenericMappingTools/pygmt/pull/620#discussion_r493088431).

What we should do is to standardize how we want +n args to be written in the documentation. This is a bit complicated, but boils down to (at least) two options:

1. r" **+n**\ *args* ". Use a raw-string in Python, allowing us to follow upstream GMT (as per https://github.com/GenericMappingTools/pygmt/pull/620#discussion_r493088431)

2. " **+n**\\ *args* ". Use a double-backslash to avoid the flake8 error W605 invalid escape sequence '\ '.

An alternative would be to find a way to ignore the flake8 error somehow for the ReST docstrings.

Also, should we find a way to put these in code-formatted blocks (i.e. with backticks), as mentioned at https://github.com/GenericMappingTools/pygmt/pull/525/files#r454746311?

Are you willing to help implement and maintain this feature? Somewhat short on time, but will look into it.

References:

• https://meta.stackexchange.com/questions/183610/how-to-combine-bold-and-code-sample-in-markdown

[seisman]

This is what PEP-257 says:

For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""".

So, instead of using r" **+n**\ *args* " for each individual cases, we should use r for the whole docstring, e.g.,

def function():
    r"""
    A long docstring string.

    We now can write doctsrings with backslashes **+n**\ *args*
    """

[seisman]

As pointed out by @weiji14, the PyGMT documentation is inconsistently using italics, bold, and code strings.

I think we can following these conventions:

1. Use code for Python function parameters
2. Use bold and italics for GMT syntax like +n**args, in which bold +n* means it should be typed as it is, and italic args* should be given a specific value.

This is a good example of what it looks like (https://www.pygmt.org/dev/tutorials/frames.html):

[seisman]

Ping @GenericMappingTools/python @willschlitzer for thoughts on this.

[willschlitzer]

@seisman I like this convention for explaining literal titles and the associated arguments that go with them. Are you thinking there should be similar formatting in the string of arguments given in the doctstring?

[seisman]

Are you thinking there should be similar formatting in the string of arguments given in the doctstring?

Yes, but need feedbacks first.

[seisman]

Ping @GenericMappingTools/python for comments.

[seisman]

Ping @GenericMappingTools/python, @GenericMappingTools/python-maintainers and @GenericMappingTools/python-contributors for thoughts on https://github.com/GenericMappingTools/pygmt/issues/631#issuecomment-747532492 and https://github.com/GenericMappingTools/pygmt/issues/631#issuecomment-747806369.

[weiji14]

Let's go with Option 1 (using the raw string). Easier to copy from GMT, and avoids messy backslashes. Also agree on the backtick code blocks.

Will need to document this (with an example) somewhere in CONTRIBUTING.md

[willschlitzer]

I think making the entire docstring a raw string is the way to go; I think a double backslash might be confusing to some, and copying directly from GMT makes life easier.

I can write this up in CONTRIBUTING.md when we come to a consensus.

[seisman]

I can write this up in CONTRIBUTING.md when we come to a consensus.

At least three of the maintainers agree with this. I think we can do it now.

[seisman]

As most of us agree with the new docstring conventions, we should do:

• [x] document the docstring conventions
• [ ] review the whole project and fix any inconsistency

[willschlitzer]

When referencing and explaining the written code in documentation, should it all be in code format or should it the bold/italicize documentation format. Some examples I encountered in earth-relief.py:

"a2500" or a**2500 "x+lElevation" or x+l**Elevation

My opinion is to leave it all as code formatting to denote that it is the literal string being passed, but I can see it both ways.

[seisman]

My opinion is to leave it all as code formatting to denote that it is the literal string being passed

I think this is the better way.

[weiji14]

I've just been looking through some of the new API docs and noticed a problem. E.g. https://www.pygmt.org/dev/api/generated/pygmt.Figure.coast.html after #765 looks like this:

I think we need to add a fullstop/period (.) between [+z] and Select ... to break the flow, or have Select ... appear on a newline as in the GMT docs:

[weiji14]

Anything else remaining after #862?

[seisman]

Some module-specific arguments still need updates, for example, basemap's map_scale argument.

[maxrjones]

Some module-specific arguments still need updates, for example, basemap's map_scale argument.

Let me know if you'd like me to help with updating these.

[willschlitzer]

@meghanrjones Please do! I'm planning on going through the documentation tomorrow; no complaints if you submit a PR for changes!

[maxrjones]

@meghanrjones Please do! I'm planning on going through the documentation tomorrow; no complaints if you submit a PR for changes!

Sounds good. I'll try to get it done before then.

[seisman]

@meghanrjones Please do! I'm planning on going through the documentation tomorrow; no complaints if you submit a PR for changes!

Sounds good. I'll try to get it done before then.

Great! Please try your best to follow the standards as documented here (https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md#example-code-standards).

There may be some cases that are not covered by the standards. We can discuss more later.

[maxrjones]

Is the convention for documenting defaults in PyGMT set? In GMT, it is typically brackets [ ] without any explanation before the default. I remember a comment in which @seisman mentioned that "[Default is ...]" is more clear than just "[...]", but I couldn't find that comment again.

[seisman]

In GMT, it is typically brackets [ ] without any explanation before the default. I remember a comment in which @seisman mentioned that "[Default is ...]" is more clear than just "[...]",

Yes, it's open for discussions. The GMT documentation sometimes also uses "[Default is ...]".

[maxrjones]

Moving forward is seems that the GMT documentation will be going with "[Default is ...]" (see https://github.com/GenericMappingTools/gmt/pull/4834).

[seisman]

Moving forward is seems that the GMT documentation will be going with "[Default is ...]" (see GenericMappingTools/gmt#4834).

I think we can document it in the "Example code standards" section, then close the issue, right?

[maxrjones]

Moving forward is seems that the GMT documentation will be going with "[Default is ...]" (see GenericMappingTools/gmt#4834).

I think we can document it in the "Example code standards" section, then close the issue, right?

Yes, I can add that guideline after #1126 is merged.