Figure.plot/Figure.plot3d: Improve the docstrings for straight_line

[seisman]

See the upstream issue report GenericMappingTools/gmt#8645 for context.

Here is an exmaple to prove that m|y|r and p|x|t have the same effects:

import pygmt
fig = pygmt.Figure()
values = [False, True, "m", "p", "r", "t", "x", "y"]
for arg in values:
    fig.basemap(region=[0, 360, -90, 90], projection="H6c", frame=[f"WSen+t-A={arg}"])
    fig.plot(x=[90, 200], y=[-50, 50], pen="1p", straight_line=arg)
    fig.shift_origin(xshift="w+1")

fig.shift_origin(xshift="-8w-8", yshift="h+3")

for arg in values:
    fig.basemap(region=[0, 10, 1, 10], projection="X6c", frame=[f"WSen+t-A={arg}"])
    fig.plot(x=[3, 8], y=[2, 7], pen="1p", straight_line=arg)
    fig.shift_origin(xshift="w+1")

fig.shift_origin(xshift="-8w-8", yshift="h+3")

for arg in values:
    fig.basemap(region=[0, 360, 0, 1], projection="P6c", frame=[f"WSen+t-A={arg}"])
    fig.plot(x=[0, 90], y=[0.2, 0.5], pen="1p", straight_line=arg)
    fig.shift_origin(xshift="w+1")
fig.show()

---

The upstream documentation will simplify plot/plot3d's -A[m|p|r|t|x|y] to -A[x|y], and we will do the similar thing in the PyGMT side.

This PR rephrases the docstrings for straight_line.

Preview: https://pygmt-dev--3720.org.readthedocs.build/en/3720/api/generated/pygmt.Figure.plot.html

TODO:

• Polish and finalize the docstrings for straight_line
• Make the same change for Figure.plot3d
• Apply the same changes (with minor changes) to the upstream documentation

[yvonnefroehlich]

I am not really familiar with this parameter, and maybe I am wrong or confused by myself. I can follow the cases for "Cartesian" and "Polar", but for "Geographic" I am wondering if there is something mixed up. Looking at the image at the beginning of this PR (I reduced the example and added a red point at the starting point): For A="x", it's first in north-south direction (varying latitude, constant longitude, i.e. meridian) and then in east-west direction (varying longitude, constant latitude, i.e. parallel); and for A="y" it's the other way around. At the moment it looks to me a bit like that (only for the Geographic case) for the "x" and "y" arguments, people defined the x-axis as latitude (vertical) and the y-axis as longitude (horizontal), which is the other way around as the input data points are given. Comparing the images for the "Geographic" case with the images for the "Cartesian" case, I would expect the images for the "Geographic" case to be switched:

import pygmt

fig = pygmt.Figure()
values = ["x", "y"]

for arg in values:
    fig.basemap(region=[0, 10, 1, 10], projection="X6c", frame=[f"WSen+t-A={arg}"])
    fig.plot(x=[3, 8], y=[2, 7], pen="1p", straight_line=arg)
    fig.plot(x=3, y=2, style="c0.2c", fill="red")
    fig.shift_origin(xshift="w+1")

fig.shift_origin(xshift="-2w-2", yshift="h+2")

for arg in values:
    fig.basemap(region=[0, 360, -90, 90], projection="H6c", frame=[f"WSen+t-A={arg}"])
    fig.plot(x=[90, 200], y=[-50, 50], pen="1p", straight_line=arg)
    fig.plot(x=90, y=-50, style="c0.2c", fill="red")
    fig.shift_origin(xshift="w+1")

fig.show()

[seisman]

Nice catch. It looks more like an upstream bug. Need time to verify it.

[seisman]

It's confirmed to be an upstream bug at GenericMappingTools/gmt#8645 and has been fixed in GenericMappingTools/gmt#8648.

Unfortunately, there is no way to determine the type (Cartesian, polar or geographic) of the current coordinate system via public GMT APIs, so we can't have a fix on the PyGMT side. Instead, I have added a note for the bug 9aa8f97