We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
add api docs for plot_energy
https://arviz-devs.github.io/arviz/generated/arviz.plot_energy.html#arviz.plot_energy

See Posterior Docs for example
https://arviz-devs.github.io/arviz/generated/arviz.plot_posterior.html#arviz.plot_posterior

--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `arviz/plots/energyplot.py`
Content:
```
1 """Plot energy transition distribution in HMC inference."""
2 import numpy as np
3 import matplotlib.pyplot as plt
4 
5 from ..data import convert_to_dataset
6 from ..stats import bfmi as e_bfmi
7 from .kdeplot import plot_kde
8 from .plot_utils import _scale_fig_size
9 
10 
11 def plot_energy(
12     data,
13     kind="kde",
14     bfmi=True,
15     figsize=None,
16     legend=True,
17     fill_alpha=(1, 0.75),
18     fill_color=("C0", "C5"),
19     bw=4.5,
20     textsize=None,
21     fill_kwargs=None,
22     plot_kwargs=None,
23     ax=None,
24 ):
25     """Plot energy transition distribution and marginal energy distribution in HMC algorithms.
26 
27     This may help to diagnose poor exploration by gradient-based algorithms like HMC or NUTS.
28 
29     Parameters
30     ----------
31     data : xarray dataset, or object that can be converted (must represent
32            `sample_stats` and have an `energy` variable)
33     kind : str
34         Type of plot to display (kde or histogram)
35     bfmi : bool
36         If True add to the plot the value of the estimated Bayesian fraction of missing information
37     figsize : tuple
38         Figure size. If None it will be defined automatically.
39     legend : bool
40         Flag for plotting legend (defaults to True)
41     fill_alpha : tuple of floats
42         Alpha blending value for the shaded area under the curve, between 0
43         (no shade) and 1 (opaque). Defaults to (1, .75)
44     fill_color : tuple of valid matplotlib color
45         Color for Marginal energy distribution and Energy transition distribution.
46         Defaults to ('C0', 'C5')
47     bw : float
48         Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the
49         smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott's rule
50         of thumb (the default rule used by SciPy). Only works if `kind='kde'`
51     textsize: float
52         Text size scaling factor for labels, titles and lines. If None it will be autoscaled based
53         on figsize.
54     fill_kwargs : dicts, optional
55         Additional keywords passed to `arviz.plot_kde` (to control the shade)
56     plot_kwargs : dicts, optional
57         Additional keywords passed to `arviz.plot_kde` or `plt.hist` (if type='hist')
58     ax : axes
59         Matplotlib axes.
60 
61     Returns
62     -------
63     ax : matplotlib axes
64     """
65     energy = convert_to_dataset(data, group="sample_stats").energy.values
66 
67     if ax is None:
68         _, ax = plt.subplots(figsize=figsize, constrained_layout=True)
69 
70     if fill_kwargs is None:
71         fill_kwargs = {}
72 
73     if plot_kwargs is None:
74         plot_kwargs = {}
75 
76     figsize, _, _, xt_labelsize, linewidth, _ = _scale_fig_size(figsize, textsize, 1, 1)
77 
78     series = zip(
79         fill_alpha,
80         fill_color,
81         ("Marginal Energy", "Energy transition"),
82         (energy - energy.mean(), np.diff(energy)),
83     )
84 
85     if kind == "kde":
86         for alpha, color, label, value in series:
87             fill_kwargs["alpha"] = alpha
88             fill_kwargs["color"] = color
89             plot_kwargs.setdefault("color", color)
90             plot_kwargs.setdefault("alpha", 0)
91             plot_kwargs.setdefault("linewidth", linewidth)
92             plot_kde(
93                 value,
94                 bw=bw,
95                 label=label,
96                 textsize=xt_labelsize,
97                 plot_kwargs=plot_kwargs,
98                 fill_kwargs=fill_kwargs,
99                 ax=ax,
100             )
101 
102     elif kind == "hist":
103         for alpha, color, label, value in series:
104             ax.hist(
105                 value.flatten(),
106                 bins="auto",
107                 density=True,
108                 alpha=alpha,
109                 label=label,
110                 color=color,
111                 **plot_kwargs
112             )
113 
114     else:
115         raise ValueError("Plot type {} not recognized.".format(kind))
116 
117     if bfmi:
118         for idx, val in enumerate(e_bfmi(energy)):
119             ax.plot([], label="chain {:>2} BFMI = {:.2f}".format(idx, val), alpha=0)
120 
121     ax.set_xticks([])
122     ax.set_yticks([])
123 
124     if legend:
125         ax.legend()
126 
127     return ax
128
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/arviz/plots/energyplot.py b/arviz/plots/energyplot.py
--- a/arviz/plots/energyplot.py
+++ b/arviz/plots/energyplot.py
@@ -61,6 +61,25 @@
     Returns
     -------
     ax : matplotlib axes
+
+    Examples
+    --------
+    Plot a default energy plot
+
+    .. plot::
+        :context: close-figs
+
+        >>> import arviz as az
+        >>> data = az.load_arviz_data('centered_eight')
+        >>> az.plot_energy(data)
+
+    Represent energy plot via histograms
+
+    .. plot::
+        :context: close-figs
+
+        >>> az.plot_energy(data, kind='hist')
+
     """
     energy = convert_to_dataset(data, group="sample_stats").energy.values

{"golden_diff": "diff --git a/arviz/plots/energyplot.py b/arviz/plots/energyplot.py\n--- a/arviz/plots/energyplot.py\n+++ b/arviz/plots/energyplot.py\n@@ -61,6 +61,25 @@\n     Returns\n     -------\n     ax : matplotlib axes\n+\n+    Examples\n+    --------\n+    Plot a default energy plot\n+\n+    .. plot::\n+        :context: close-figs\n+\n+        >>> import arviz as az\n+        >>> data = az.load_arviz_data('centered_eight')\n+        >>> az.plot_energy(data)\n+\n+    Represent energy plot via histograms\n+\n+    .. plot::\n+        :context: close-figs\n+\n+        >>> az.plot_energy(data, kind='hist')\n+\n     \"\"\"\n     energy = convert_to_dataset(data, group=\"sample_stats\").energy.values\n", "issue": "add api docs for plot_energy\nhttps://arviz-devs.github.io/arviz/generated/arviz.plot_energy.html#arviz.plot_energy\r\n\r\nSee Posterior Docs for example\r\nhttps://arviz-devs.github.io/arviz/generated/arviz.plot_posterior.html#arviz.plot_posterior\n", "before_files": [{"content": "\"\"\"Plot energy transition distribution in HMC inference.\"\"\"\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nfrom ..data import convert_to_dataset\nfrom ..stats import bfmi as e_bfmi\nfrom .kdeplot import plot_kde\nfrom .plot_utils import _scale_fig_size\n\n\ndef plot_energy(\n    data,\n    kind=\"kde\",\n    bfmi=True,\n    figsize=None,\n    legend=True,\n    fill_alpha=(1, 0.75),\n    fill_color=(\"C0\", \"C5\"),\n    bw=4.5,\n    textsize=None,\n    fill_kwargs=None,\n    plot_kwargs=None,\n    ax=None,\n):\n    \"\"\"Plot energy transition distribution and marginal energy distribution in HMC algorithms.\n\n    This may help to diagnose poor exploration by gradient-based algorithms like HMC or NUTS.\n\n    Parameters\n    ----------\n    data : xarray dataset, or object that can be converted (must represent\n           `sample_stats` and have an `energy` variable)\n    kind : str\n        Type of plot to display (kde or histogram)\n    bfmi : bool\n        If True add to the plot the value of the estimated Bayesian fraction of missing information\n    figsize : tuple\n        Figure size. If None it will be defined automatically.\n    legend : bool\n        Flag for plotting legend (defaults to True)\n    fill_alpha : tuple of floats\n        Alpha blending value for the shaded area under the curve, between 0\n        (no shade) and 1 (opaque). Defaults to (1, .75)\n    fill_color : tuple of valid matplotlib color\n        Color for Marginal energy distribution and Energy transition distribution.\n        Defaults to ('C0', 'C5')\n    bw : float\n        Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the\n        smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott's rule\n        of thumb (the default rule used by SciPy). Only works if `kind='kde'`\n    textsize: float\n        Text size scaling factor for labels, titles and lines. If None it will be autoscaled based\n        on figsize.\n    fill_kwargs : dicts, optional\n        Additional keywords passed to `arviz.plot_kde` (to control the shade)\n    plot_kwargs : dicts, optional\n        Additional keywords passed to `arviz.plot_kde` or `plt.hist` (if type='hist')\n    ax : axes\n        Matplotlib axes.\n\n    Returns\n    -------\n    ax : matplotlib axes\n    \"\"\"\n    energy = convert_to_dataset(data, group=\"sample_stats\").energy.values\n\n    if ax is None:\n        _, ax = plt.subplots(figsize=figsize, constrained_layout=True)\n\n    if fill_kwargs is None:\n        fill_kwargs = {}\n\n    if plot_kwargs is None:\n        plot_kwargs = {}\n\n    figsize, _, _, xt_labelsize, linewidth, _ = _scale_fig_size(figsize, textsize, 1, 1)\n\n    series = zip(\n        fill_alpha,\n        fill_color,\n        (\"Marginal Energy\", \"Energy transition\"),\n        (energy - energy.mean(), np.diff(energy)),\n    )\n\n    if kind == \"kde\":\n        for alpha, color, label, value in series:\n            fill_kwargs[\"alpha\"] = alpha\n            fill_kwargs[\"color\"] = color\n            plot_kwargs.setdefault(\"color\", color)\n            plot_kwargs.setdefault(\"alpha\", 0)\n            plot_kwargs.setdefault(\"linewidth\", linewidth)\n            plot_kde(\n                value,\n                bw=bw,\n                label=label,\n                textsize=xt_labelsize,\n                plot_kwargs=plot_kwargs,\n                fill_kwargs=fill_kwargs,\n                ax=ax,\n            )\n\n    elif kind == \"hist\":\n        for alpha, color, label, value in series:\n            ax.hist(\n                value.flatten(),\n                bins=\"auto\",\n                density=True,\n                alpha=alpha,\n                label=label,\n                color=color,\n                **plot_kwargs\n            )\n\n    else:\n        raise ValueError(\"Plot type {} not recognized.\".format(kind))\n\n    if bfmi:\n        for idx, val in enumerate(e_bfmi(energy)):\n            ax.plot([], label=\"chain {:>2} BFMI = {:.2f}\".format(idx, val), alpha=0)\n\n    ax.set_xticks([])\n    ax.set_yticks([])\n\n    if legend:\n        ax.legend()\n\n    return ax\n", "path": "arviz/plots/energyplot.py"}], "after_files": [{"content": "\"\"\"Plot energy transition distribution in HMC inference.\"\"\"\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nfrom ..data import convert_to_dataset\nfrom ..stats import bfmi as e_bfmi\nfrom .kdeplot import plot_kde\nfrom .plot_utils import _scale_fig_size\n\n\ndef plot_energy(\n    data,\n    kind=\"kde\",\n    bfmi=True,\n    figsize=None,\n    legend=True,\n    fill_alpha=(1, 0.75),\n    fill_color=(\"C0\", \"C5\"),\n    bw=4.5,\n    textsize=None,\n    fill_kwargs=None,\n    plot_kwargs=None,\n    ax=None,\n):\n    \"\"\"Plot energy transition distribution and marginal energy distribution in HMC algorithms.\n\n    This may help to diagnose poor exploration by gradient-based algorithms like HMC or NUTS.\n\n    Parameters\n    ----------\n    data : xarray dataset, or object that can be converted (must represent\n           `sample_stats` and have an `energy` variable)\n    kind : str\n        Type of plot to display (kde or histogram)\n    bfmi : bool\n        If True add to the plot the value of the estimated Bayesian fraction of missing information\n    figsize : tuple\n        Figure size. If None it will be defined automatically.\n    legend : bool\n        Flag for plotting legend (defaults to True)\n    fill_alpha : tuple of floats\n        Alpha blending value for the shaded area under the curve, between 0\n        (no shade) and 1 (opaque). Defaults to (1, .75)\n    fill_color : tuple of valid matplotlib color\n        Color for Marginal energy distribution and Energy transition distribution.\n        Defaults to ('C0', 'C5')\n    bw : float\n        Bandwidth scaling factor for the KDE. Should be larger than 0. The higher this number the\n        smoother the KDE will be. Defaults to 4.5 which is essentially the same as the Scott's rule\n        of thumb (the default rule used by SciPy). Only works if `kind='kde'`\n    textsize: float\n        Text size scaling factor for labels, titles and lines. If None it will be autoscaled based\n        on figsize.\n    fill_kwargs : dicts, optional\n        Additional keywords passed to `arviz.plot_kde` (to control the shade)\n    plot_kwargs : dicts, optional\n        Additional keywords passed to `arviz.plot_kde` or `plt.hist` (if type='hist')\n    ax : axes\n        Matplotlib axes.\n\n    Returns\n    -------\n    ax : matplotlib axes\n\n    Examples\n    --------\n    Plot a default energy plot\n\n    .. plot::\n        :context: close-figs\n\n        >>> import arviz as az\n        >>> data = az.load_arviz_data('centered_eight')\n        >>> az.plot_energy(data)\n\n    Represent energy plot via histograms\n\n    .. plot::\n        :context: close-figs\n\n        >>> az.plot_energy(data, kind='hist')\n\n    \"\"\"\n    energy = convert_to_dataset(data, group=\"sample_stats\").energy.values\n\n    if ax is None:\n        _, ax = plt.subplots(figsize=figsize, constrained_layout=True)\n\n    if fill_kwargs is None:\n        fill_kwargs = {}\n\n    if plot_kwargs is None:\n        plot_kwargs = {}\n\n    figsize, _, _, xt_labelsize, linewidth, _ = _scale_fig_size(figsize, textsize, 1, 1)\n\n    series = zip(\n        fill_alpha,\n        fill_color,\n        (\"Marginal Energy\", \"Energy transition\"),\n        (energy - energy.mean(), np.diff(energy)),\n    )\n\n    if kind == \"kde\":\n        for alpha, color, label, value in series:\n            fill_kwargs[\"alpha\"] = alpha\n            fill_kwargs[\"color\"] = color\n            plot_kwargs.setdefault(\"color\", color)\n            plot_kwargs.setdefault(\"alpha\", 0)\n            plot_kwargs.setdefault(\"linewidth\", linewidth)\n            plot_kde(\n                value,\n                bw=bw,\n                label=label,\n                textsize=xt_labelsize,\n                plot_kwargs=plot_kwargs,\n                fill_kwargs=fill_kwargs,\n                ax=ax,\n            )\n\n    elif kind == \"hist\":\n        for alpha, color, label, value in series:\n            ax.hist(\n                value.flatten(),\n                bins=\"auto\",\n                density=True,\n                alpha=alpha,\n                label=label,\n                color=color,\n                **plot_kwargs\n            )\n\n    else:\n        raise ValueError(\"Plot type {} not recognized.\".format(kind))\n\n    if bfmi:\n        for idx, val in enumerate(e_bfmi(energy)):\n            ax.plot([], label=\"chain {:>2} BFMI = {:.2f}\".format(idx, val), alpha=0)\n\n    ax.set_xticks([])\n    ax.set_yticks([])\n\n    if legend:\n        ax.legend()\n\n    return ax\n", "path": "arviz/plots/energyplot.py"}]}