Figure.shift_origin: Improve docstrings, add inline examples and add type hints

[seisman]

Description of proposed changes

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

[seisman]

Ping @GenericMappingTools/pygmt-maintainers

Since we're working on the Figure.shift_origin function in this PR, I'd like to hear your thoughts about whether we should use xshift=5 or xshift="5c" in our gallery examples.

As mentioned in the updated docstrings:

Optionally, append the length unit (c for centimeters, i for inches, or p for points) to the shifts. Default unit if not explicitly given is c, but can be changed to other units via :gmt-term:PROJ_LENGTH_UNIT.

So, by default xshift=5 is the same as xshift="5c", but the default unit c can be changed by PROJ_LENGTH_UNIT or by setting set (UNITS "US") when building GMT source codes.

Personally, I prefer to xshift=5 for its simplicity. It's noteworthy to know that GMT recommends "always append the desired unit explicitly" (https://docs.generic-mapping-tools.org/dev/reference/features.html#dimension-units), but I feel we don't have to follow the recommendation in PyGMT.

Here are gallery examples that use xshift/yshift.

$ grep 'xshift=' examples/**/*.py
examples/gallery/3d_plots/scatter3d.py:fig.shift_origin(xshift=3.1)
examples/gallery/histograms/blockm.py:fig.shift_origin(xshift="w+5c")
examples/gallery/histograms/scatter_and_histograms.py:fig.shift_origin(yshift="-10.25c", xshift="10.25c")
examples/gallery/images/grdclip.py:fig.shift_origin(xshift="w+0.5c")
examples/gallery/images/grdgradient.py:fig.shift_origin(xshift="12.5c")
examples/gallery/lines/envelope.py:fig.shift_origin(xshift="11c")
examples/gallery/lines/envelope.py:fig.shift_origin(xshift="11c")
examples/projections/nongeo/polar.py:fig.shift_origin(xshift="8c")
examples/projections/nongeo/polar.py:fig.shift_origin(xshift="8c")
examples/projections/nongeo/polar.py:fig.shift_origin(xshift="-16c", yshift="-7c")
examples/projections/nongeo/polar.py:fig.shift_origin(xshift="8c", yshift="1.3c")
examples/projections/nongeo/polar.py:fig.shift_origin(xshift="8c")
examples/tutorials/advanced/cartesian_histograms.py:fig.shift_origin(xshift="12c")
examples/tutorials/advanced/cartesian_histograms.py:fig.shift_origin(xshift="12c")
examples/tutorials/advanced/cartesian_histograms.py:fig.shift_origin(xshift="11c")
examples/tutorials/advanced/cartesian_histograms.py:fig.shift_origin(xshift="11c")
examples/tutorials/basics/coastlines.py:    fig.shift_origin(xshift="5c")

$ grep 'yshift=' examples/**/*.py
examples/gallery/histograms/scatter_and_histograms.py:fig.shift_origin(yshift="10.25c")
examples/gallery/histograms/scatter_and_histograms.py:fig.shift_origin(yshift="-10.25c", xshift="10.25c")
examples/gallery/images/cross_section.py:fig.shift_origin(yshift="12.5c")
examples/projections/nongeo/polar.py:fig.shift_origin(xshift="-16c", yshift="-7c")
examples/projections/nongeo/polar.py:fig.shift_origin(xshift="8c", yshift="1.3c")
examples/tutorials/advanced/configuration.py:fig.shift_origin(yshift="-10c")
examples/tutorials/advanced/subplots.py:fig.shift_origin(yshift="h+1c")

[codspeed-hq]

CodSpeed Performance Report

Merging #2879 will not alter performance

_{⚠️ No base runs were found}

_{Falling back to comparing docs/shift_origin (1148c88) with main (e0593d2)}

Summary

✅ 64 untouched benchmarks

[weiji14]

So, by default xshift=5 is the same as xshift="5c", but the default unit c can be changed by PROJ_LENGTH_UNIT or by setting set (UNITS "US") when building GMT source codes.

Personally, I prefer to xshift=5 for its simplicity. It's noteworthy to know that GMT recommends "always append the desired unit explicitly" (https://docs.generic-mapping-tools.org/dev/reference/features.html#dimension-units), but I feel we don't have to follow the recommendation in PyGMT.

I'd prefer to explicitly use 5c so that people copying and pasing the code can reproduce the same figure even with a different PROJ_LENGTH_UNIT. We had some PRs that were strongly in favour of SI Units before (e.g. #719, #795).

[seisman]

So, by default xshift=5 is the same as xshift="5c", but the default unit c can be changed by PROJ_LENGTH_UNIT or by setting set (UNITS "US") when building GMT source codes.
Personally, I prefer to xshift=5 for its simplicity. It's noteworthy to know that GMT recommends "always append the desired unit explicitly" (https://docs.generic-mapping-tools.org/dev/reference/features.html#dimension-units), but I feel we don't have to follow the recommendation in PyGMT.

I'd prefer to explicitly use 5c so that people copying and pasing the code can reproduce the same figure even with a different PROJ_LENGTH_UNIT. We had some PRs that were strongly in favour of SI Units before (e.g. #719, #795).

OK. Updated one instance in 7ece697.

[yvonnefroehlich]

Only passing the value is nice because of shortness and data type. But I feel for the examples, it is better to keep the unit because:

• It's directly clear to the user which unit is used.
• It's clear to the user that a specific unit can be specified.
• If the user has changed the default value, the figure looks different from the one we have in the documentation. Maybe this is confusing, especially if the user is not familiar with setting the GMT defaults.
• I agree with @weiji14's SI unit argument.