Unable to use aspect="equal" in plot.imshow() whereas option is given in the doc

What is your issue?

I'm using the version 2023.12.0.

In the doc of imshow (https://docs.xarray.dev/en/stable/generated/xarray.DataArray.plot.imshow.html) it is written for the aspect parameter:

aspect ("auto", "equal", scalar or None, optional) – Aspect ratio of plot, so that aspect * size gives the width in inches. Only used if a size is provided.

But if I try this simple code:

import xarray as xr
import numpy as np
import matplotlib.pyplot as plt

data_array = np.random.randint(0, 255, size=(3, 2), dtype=np.uint8)
xarray_data = xr.DataArray(data_array, dims=('dim1', 'dim2'))
xarray_data.plot.imshow(size=5, aspect="equal")
plt.show()

I get the following error:

...
  File "...\lib\site-packages\xarray\plot\dataarray_plot.py", line 1598, in newplotfunc
    raise ValueError("plt.imshow's `aspect` kwarg is not available in xarray")
ValueError: plt.imshow's `aspect` kwarg is not available in xarray

Indeed in the code here there is:

        if "imshow" == plotfunc.__name__ and isinstance(aspect, str):
            # forbid usage of mpl strings
            raise ValueError("plt.imshow's `aspect` kwarg is not available in xarray")

which seems quite clear.

So is there something I'm doing wrong or is it an issue between doc and code ? Thanks !

Reproduce the example first, then inspect xarray/plot/dataarray_plot.py around the imshow aspect guard and compare it with the linked DataArray.plot.imshow documentation. Determine whether the documented aspect values or the implementation should be aligned, update the relevant behavior or documentation, and add coverage for the resolved behavior.