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 #525 (comment) and #620 (comment)).

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 Complete documentation of grdimage #620 (comment))

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 +nargs, 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 #631 (comment) and #631 (comment).

[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:

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