Added references in plot_dot and plot_dist_comparison (#1926)

* WIP

* WIP

* rebased with main

arviz/plots/distcomparisonplot.py

@@ -32,8 +32,8 @@ def plot_dist_comparison(
 
     Parameters
     ----------
-    data : az.InferenceData object
-        InferenceData object containing the posterior/prior data.
+    data : InferenceData object
+        :class:`arviz.InferenceData` object containing the posterior/prior data.
     kind : str
         kind of plot to display {"latent", "observed"}, defaults to 'latent'.
         "latent" includes {"prior", "posterior"} and "observed" includes
@@ -42,7 +42,7 @@ def plot_dist_comparison(
         Figure size. If None it will be defined automatically.
     textsize: float
         Text size scaling factor for labels, titles and lines. If None it will be
-        autoscaled based on figsize.
+        autoscaled based on ``figsize``.
     var_names : str, list, list of lists
         if str, plot the variable. if list, plot all the variables in list
         of all groups. if list of lists, plot the vars of groups in respective lists.
@@ -55,31 +55,37 @@ def plot_dist_comparison(
     legend : bool
         Add legend to figure. By default True.
     labeller : labeller instance, optional
-        Class providing the method `make_pp_label` to generate the labels in the plot.
+        Class providing the method ``make_pp_label`` to generate the labels in the plot.
         Read the :ref:`label_guide` for more details and usage examples.
     ax: axes, optional
         Matplotlib axes: The ax argument should have shape (nvars, 3), where the
         last column is for the combined before/after plots and columns 0 and 1 are
         for the before and after plots, respectively.
     prior_kwargs : dicts, optional
-        Additional keywords passed to `arviz.plot_dist` for prior/predictive groups.
+        Additional keywords passed to :func:`arviz.plot_dist` for prior/predictive groups.
     posterior_kwargs : dicts, optional
-        Additional keywords passed to `arviz.plot_dist` for posterior/predictive groups.
+        Additional keywords passed to :func:`arviz.plot_dist` for posterior/predictive groups.
     observed_kwargs : dicts, optional
-        Additional keywords passed to `arviz.plot_dist` for observed_data group.
+        Additional keywords passed to :func:`arviz.plot_dist` for observed_data group.
     backend: str, optional
         Select plotting backend {"matplotlib","bokeh"}. Default "matplotlib".
     backend_kwargs: bool, optional
-        These are kwargs specific to the backend being used. For additional documentation
+        These are kwargs specific to the backend being used, passed to
+        :func:`matplotlib.pyplot.subplots` or
+        :func:`bokeh.plotting.figure`. For additional documentation
         check the plotting method of the backend.
     show : bool, optional
         Call backend show function.
 
     Returns
     -------
-    axes : a numpy 2d array of matplotlib axes. Returned object will have shape (nvars, 3),
+    axes : a numpy 2D array of matplotlib axes. Returned object will have shape (nvars, 3),
     where the last column is the combined plot and the first columns are the single plots.
 
+    See Also
+    --------
+    plot_bpv : Plot Bayesian p-value for observed data and Posterior/Prior predictive.
+
     Examples
     --------
     Plot the prior/posterior plot for specified vars and coords.

arviz/plots/dotplot.py

@@ -48,7 +48,7 @@ def plot_dot(
         The distance between the center of the dots in the same stack relative to the bin height.
         The default, 1, makes dots in the same stack just touch each other.
     point_interval : bool, optional
-        Plots the point interval. Uses hdi_prob to plot the HDI interval
+        Plots the point interval. Uses ``hdi_prob`` to plot the HDI interval
     point_estimate : str, optional
         Plot point estimate per variable. Values should be ‘mean’, ‘median’, ‘mode’ or None.
         Defaults to ‘auto’ i.e. it falls back to default set in rcParams.
@@ -57,14 +57,14 @@ def plot_dot(
     intervalcolor : string, optional
         The color of the interval. Should be a valid matplotlib color.
     linewidth : int, optional
-        Line width throughout. If None it will be autoscaled based on figsize.
+        Line width throughout. If None it will be autoscaled based on ``figsize``.
     markersize : int, optional
-        Markersize throughout. If None it will be autoscaled based on figsize.
+        Markersize throughout. If None it will be autoscaled based on ``figsize``.
     markercolor: string, optional
         The color of the marker when plot_interval is True. Should be a valid matplotlib color.
     marker: string, optional
         The shape of the marker. Valid for matplotlib backend
-        Defaults to "o"
+        Defaults to "o".
     hdi_prob : float, optional
         Valid only when point_interval is True. Plots HDI for chosen percentage of density.
         Defaults to ``stats.hdi_prob`` rcParam.
@@ -79,7 +79,7 @@ def plot_dot(
     figsize : tuple, optional
         Figure size. If None it will be defined automatically.
     plot_kwargs : dict, optional
-        Keywords passed for customizing the dots. Passed to :meth:`mpl:matplotlib.patches.Circle`
+        Keywords passed for customizing the dots. Passed to :class:`mpl:matplotlib.patches.Circle`
         in matplotlib and :meth:`bokeh:bokeh.plotting.Figure.circle` in bokeh
     backend: str, optional
         Select plotting backend {"matplotlib","bokeh"}. Default "matplotlib".
@@ -89,13 +89,18 @@ def plot_dot(
         Call backend show function.
     backend_kwargs: dict, optional
         These are kwargs specific to the backend being used, passed to
-        :func:`mpl:matplotlib.pyplot.subplots` or
-        :meth:`bokeh:bokeh.plotting.figure`.
+        :func:`matplotlib.pyplot.subplots` or
+        :func:`bokeh.plotting.figure`. For additional documentation
+        check the plotting method of the backend.
 
     Returns
     -------
     axes : matplotlib axes or bokeh figures
 
+    See Also
+    --------
+    plot_dist : Plot distribution as histogram or kernel density estimates.
+
     References
     ----------
     .. [1] Leland Wilkinson (1999) Dot Plots, The American Statistician, 53:3, 276-281,