Update COMMON_OPTIONS arguments to GMT standard

[willschlitzer]

Update the argument doc strings in the COMMON_OPTIONS dictionary in decorators.py to the standard set in #631.

[willschlitzer]

I can't figure out why this is failing so many tests, as it is changing the content of strings and no functions. It appears to be rendering correctly when it is built in Sphinx.

[seisman]

One doctest in pygmt.helpers.decorators.fmt_docstring fails.

=================================== FAILURES ===================================
_______________ [doctest] pygmt.helpers.decorators.fmt_docstring _______________
160     ...
161     ...     Parameters
162     ...     ----------
163     ...     {R}
164     ...     {J}
165     ...
166     ...     {aliases}
167     ...     '''
168     ...     pass
169     >>> print(gmtinfo.__doc__)
Differences (unified diff with -expected +actual):
    @@ -5,10 +5,11 @@
     ----------
     region : str or list
    -    *Required if this is the first plot command*.
    -    ``'xmin/xmax/ymin/ymax[+r][+uunit]'``.
    -    Specify the region of interest.
    +    *xmin/xmax/ymin/ymax*\ [**+r**\ ][**+u**\ *unit*]
    +    Specify the region of interest. This is a required argument if this 
    +    is the first plot command.
     projection : str
    -    *Required if this is the first plot command*.
    -    Select map projection.
    +    *projection*\ [*projection-specific arguments*\ ]*figure size*
    +    Select map projection. This is a required argument if this 
    +    is the first plot command.
     <BLANKLINE>
     **Aliases:**

[willschlitzer]

I misinterpreted the 12 xfailed as test failures then. Regardless, I can't see how this is causing a doctest failure, so I'm not sure how to fix the strings to make it pass.

[seisman]

I misinterpreted the 12 xfailed as test failures then.

They are "known" failures.

I can't see how this is causing a doctest failure, so I'm not sure how to fix the strings to make it pass.

You need to update these lines:

pygmt/pygmt/helpers/decorators.py

Lines 172 to 180 in 547a6fc

	Parameters
	----------
	region : str or list
	*Required if this is the first plot command*.
	``'xmin/xmax/ymin/ymax[+r][+uunit]'``.
	Specify the region of interest.
	projection : str
	*Required if this is the first plot command*.
	Select map projection.

[weiji14]

I reckon this PR is about done, just a few more changes needed.

[weiji14]

Suggested change

	"R": """\
	"R": r"""\

Need to make this a raw r-string to avoid the pylint warning (W605 invalid escape sequence '\ ')

[willschlitzer]

It rendered incorrectly when I would have raw strings in both COMMON_OPTIONS and the function doc strings (check out the deployment for 62e8aad at the top). My guess is some issue with a raw string with escape characters being passed into another raw string.

[weiji14]

I see, might need to rethink this a bit then or just ignore the pylint error if it's harmless.

[willschlitzer]

Should I add a pylint: disable=invalid-escape-sequence (is that the correct wording/syntax?)?

[seisman]

-J option is very difficult to read.

[seisman]

The Y option is not correctly rendered.

[willschlitzer]

@seisman I tried adding blank lines to create line breaks in bc6f1e8, but that just caused tests to fail. Any idea how to fix this?

[willschlitzer]

This problem was fixed by @seisman in #862. Closing this PR.