Figure.histogram: Add parameters to annote bars and deprecate parameter 'annotate'

[seisman]

This PR provides a Pythonic implementation for the -D option. The GMT CLI syntax is:

-D[+b][+f<font>][+o<offset>][+r]

This PR maps it to multiple parameters

• annot
• +b: annot_position [default to "top"]
• +f: annot_font
• +o: annot_offset
• +r: annot_orientation

The prefix annot is preferred so that it's more consistent with Figure.colorbar and Frame. This PR also deprecates the annotate parameter to annot.

Example:

import numpy as np
import pygmt
from pygmt.params import Axis, Frame

rng = np.random.default_rng(seed=100)
mean = 100  # mean of distribution
stddev = 25  # standard deviation of distribution
data = rng.normal(loc=mean, scale=stddev, size=521)


fig = pygmt.Figure()
fig.histogram(
    data=data,
    frame=True,
    series=10,
    fill="red3",
    pen="1p",
    annot=True,
    annot_position="top",
    annot_font="8p,blue",
    annot_orientation="vertical",
    # horizontal=True, 
)
fig.show()

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

[yvonnefroehlich]

Having default = None and then giving a explicit default could be a bit confusing.

[seisman]

I think this style is used in the whole documentation. None means using the default value.

[yvonnefroehlich]

For histograms with horizontal bars, it is left and right. Maybe we could use something simliar to start and end?

[seisman]

Done in 0394768.