pydata · dcherian · Oct 17, 2022 · Sep 6, 2022 · Sep 6, 2022 · Sep 6, 2022
diff --git a/doc/api.rst b/doc/api.rst
@@ -588,60 +588,60 @@ Dataset methods
 .. autosummary::
    :toctree: generated/
 
-   open_dataset
    load_dataset
+   open_dataset
    open_mfdataset
    open_rasterio
    open_zarr
-   Dataset.to_netcdf
-   Dataset.to_pandas
-   Dataset.as_numpy
-   Dataset.to_zarr
    save_mfdataset
+   Dataset.as_numpy
+   Dataset.from_dataframe
+   Dataset.from_dict
    Dataset.to_array
    Dataset.to_dataframe
    Dataset.to_dask_dataframe
    Dataset.to_dict
-   Dataset.from_dataframe
-   Dataset.from_dict
+   Dataset.to_netcdf
+   Dataset.to_pandas
+   Dataset.to_zarr
+   Dataset.chunk
    Dataset.close
    Dataset.compute
-   Dataset.persist
-   Dataset.load
-   Dataset.chunk
-   Dataset.unify_chunks
    Dataset.filter_by_attrs
    Dataset.info
+   Dataset.load
+   Dataset.persist
+   Dataset.unify_chunks
 
 DataArray methods
 -----------------
 
 .. autosummary::
    :toctree: generated/
 
-   open_dataarray
    load_dataarray
+   open_dataarray
+   DataArray.as_numpy
+   DataArray.from_cdms2
+   DataArray.from_dict
+   DataArray.from_iris
+   DataArray.from_series
+   DataArray.to_cdms2
+   DataArray.to_dataframe
    DataArray.to_dataset
+   DataArray.to_dict
+   DataArray.to_index
+   DataArray.to_iris
+   DataArray.to_masked_array
    DataArray.to_netcdf
+   DataArray.to_numpy
    DataArray.to_pandas
    DataArray.to_series
-   DataArray.to_dataframe
-   DataArray.to_numpy
-   DataArray.as_numpy
-   DataArray.to_index
-   DataArray.to_masked_array
-   DataArray.to_cdms2
-   DataArray.to_iris
-   DataArray.from_iris
-   DataArray.to_dict
-   DataArray.from_series
-   DataArray.from_cdms2
-   DataArray.from_dict
+   DataArray.chunk
    DataArray.close
    DataArray.compute
    DataArray.persist
    DataArray.load
-   DataArray.chunk
    DataArray.unify_chunks
 
 Coordinates objects
@@ -1086,6 +1086,7 @@ Advanced API
    Dataset.set_close
    backends.BackendArray
    backends.BackendEntrypoint
+   backends.list_engines
 
 These backends provide a low-level interface for lazily loading data from
 external file-formats or protocols, and can be manually invoked to create

diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst
@@ -16,6 +16,9 @@ If you also want to support lazy loading and dask see :ref:`RST lazy_loading`.
 Note that the new interface for backends is available from Xarray
 version >= 0.18 onwards.
 
+You can see what backends are currently available in your working environment
+with :py:class:`~xarray.backends.list_engines()`.
+
 .. _RST backend_entrypoint:
 
 BackendEntrypoint subclassing
@@ -26,7 +29,9 @@ it should implement the following attributes and methods:
 
 - the ``open_dataset`` method (mandatory)
 - the ``open_dataset_parameters`` attribute (optional)
-- the ``guess_can_open`` method (optional).
+- the ``guess_can_open`` method (optional)
+- the ``description`` attribute (optional)
+- the ``url`` attribute (optional).
 
 This is what a ``BackendEntrypoint`` subclass should look like:
 
@@ -55,6 +60,10 @@ This is what a ``BackendEntrypoint`` subclass should look like:
                 return False
             return ext in {".my_format", ".my_fmt"}
 
+        description = "Use .my_format files in Xarray"
+
+        url = "https://link_to/your_backend/documentation"
+
 ``BackendEntrypoint`` subclass methods and attributes are detailed in the following.
 
 .. _RST open_dataset:
@@ -168,6 +177,17 @@ that always returns ``False``.
 Backend ``guess_can_open`` takes as input the ``filename_or_obj`` parameter of
 Xarray :py:meth:`~xarray.open_dataset`, and returns a boolean.
 
+.. _RST properties:
+
+description and url
+^^^^^^^^^^^^^^^^^^^^
+
+``description`` is used to provide a short text description of the backend.
+``url`` is used to include a link to the backend's documentation or code.
+
+These attributes are surfaced when a user prints :py:class:`~xarray.backends.BackendEntrypoint`.
+If ``description`` or ``url`` are not defined, an empty string is returned.
+
 .. _RST decoders:
 
 Decoders

diff --git a/doc/whats-new.rst b/doc/whats-new.rst
@@ -216,6 +216,10 @@ New Features
   By `Joe Hamman <https://github.com/jhamman>`_.
 - Upload development versions to `TestPyPI <https://test.pypi.org>`_.
   By `Justus Magin <https://github.com/keewis>`_.
+- Improves overall documentation around available backends, including adding docstrings for :py:meth:`xarray.backends.list_engines()`
+  Add :py:meth:`__str__` to surface the new :py:class:`BackendEntrypoint` ``description``
+  and ``url`` attributes. (:issue:`6577`, :pull:`7000`)
+  By `Jessica Scheick <https://github.com/jessicas11>`_.
 
 Breaking changes
 ~~~~~~~~~~~~~~~~

diff --git a/xarray/backends/common.py b/xarray/backends/common.py
@@ -369,10 +369,32 @@ class BackendEntrypoint:
     - ``guess_can_open`` method: it shall return ``True`` if the backend is able to open
       ``filename_or_obj``, ``False`` otherwise. The implementation of this
       method is not mandatory.
+
+    Attributes
+    ----------
+
+    open_dataset_parameters : tuple, default None
+        A list of ``open_dataset`` method parameters.
+        The setting of this attribute is not mandatory.
+    description : str
+        A short string describing the engine.
+        The setting of this attribute is not mandatory.
+    url : str
+        A string with the URL to the backend's documentation.
+        The setting of this attribute is not mandatory.
     """
 
     open_dataset_parameters: tuple | None = None
-    """list of ``open_dataset`` method parameters"""
+    description: str = ""
+    url: str = ""
+
+    def __str__(self) -> str:
+        txt = f"Backend type: {type(self).__name__}"
+        if self.description:
+            txt += f"\n{self.description}"
+        if self.url:
+            txt += f"\nLearn more at {self.url}"
+        return txt
-    description: str = ""
-    url: str = ""
-
-    def __str__(self) -> str:
-        txt = f"Backend type: {type(self).__name__}"
-        if self.description:
-            txt += f"\n{self.description}"
-        if self.url:
-            txt += f"\nLearn more at {self.url}"
-        return txt
+
+    def __repr__(self) -> str:
+        description = "Base entrypoint for backends"
+        url = r"https://xarray.dev/"
+        return f"<{type(self).__name__}>\n  {description}\n  {url}"
-    description: str = ""
-    url: str = ""
-
-    def __str__(self) -> str:
-        txt = f"Backend type: {type(self).__name__}"
-        if self.description:
-            txt += f"\n{self.description}"
-        if self.url:
-            txt += f"\nLearn more at {self.url}"
-        return txt
+
+    def __repr__(self) -> str:
+        description = "Base entrypoint for backends"
+        url = r"https://xarray.dev/"
+        return f"<{type(self).__name__}>\n  {description}\n  {url}"
 
     def open_dataset(
         self,

diff --git a/xarray/backends/plugins.py b/xarray/backends/plugins.py
@@ -99,6 +99,19 @@ def build_engines(entrypoints):
 @functools.lru_cache(maxsize=1)
 def list_engines():
     # New selection mechanism introduced with Python 3.10. See GH6514.
+    """
+    Return a dictionary of available engines and their BackendEntrypoint objects.
+
+    Returns
+    -------
+    dictionary
+
+    Notes
+    -----
+    This function lives in the backends namespace (``engs=xr.backends.list_engines()``).
+    If available, more information is available about each backend via ``engs["eng_name"]``.
+
+    """
     if sys.version_info >= (3, 10):
         entrypoints = entry_points(group="xarray.backends")
     else: