Simplify the user experience of a backend developer (imports and docs) (#5127)

* Simplify the user experience of a backend developer (imports and docs)

* Code style

* Use RST links

Author: alexamici

doc/internals/how-to-add-new-backend.rst

@@ -32,16 +32,19 @@ This is what a ``BackendEntrypoint`` subclass should look like:
 
 .. code-block:: python
 
+    from xarray.backends import BackendEntrypoint
+
+
     class MyBackendEntrypoint(BackendEntrypoint):
         def open_dataset(
             self,
             filename_or_obj,
             *,
             drop_variables=None,
             # other backend specific keyword arguments
+            # `chunks` and `cache` DO NOT go here, they are handled by xarray
         ):
-            ...
-            return ds
+            return my_open_dataset(filename_or_obj, drop_variables=drop_variables)
 
         open_dataset_parameters = ["filename_or_obj", "drop_variables"]
 
@@ -50,7 +53,7 @@ This is what a ``BackendEntrypoint`` subclass should look like:
                 _, ext = os.path.splitext(filename_or_obj)
             except TypeError:
                 return False
-            return ext in {...}
+            return ext in {".my_format", ".my_fmt"}
 
 ``BackendEntrypoint`` subclass methods and attributes are detailed in the following.
 
@@ -74,20 +77,19 @@ The following is an example of the high level processing steps:
         decode_times=True,
         decode_timedelta=True,
         decode_coords=True,
-        my_backend_param=None,
+        my_backend_option=None,
     ):
         vars, attrs, coords = my_reader(
             filename_or_obj,
             drop_variables=drop_variables,
-            my_backend_param=my_backend_param,
+            my_backend_option=my_backend_option,
         )
         vars, attrs, coords = my_decode_variables(
             vars, attrs, decode_times, decode_timedelta, decode_coords
         )  #  see also conventions.decode_cf_variables
 
-        ds = xr.Dataset(vars, attrs=attrs)
-        ds = ds.set_coords(coords)
-        ds.set_close(store.close)
+        ds = xr.Dataset(vars, attrs=attrs, coords=coords)
+        ds.set_close(my_close_method)
 
         return ds
 
@@ -98,9 +100,9 @@ method shall be set by using :py:meth:`~xarray.Dataset.set_close`.
 
 
 The input of ``open_dataset`` method are one argument
-(``filename``) and one keyword argument (``drop_variables``):
+(``filename_or_obj``) and one keyword argument (``drop_variables``):
 
-- ``filename``: can be a string containing a path or an instance of
+- ``filename_or_obj``: can be any object but usually it is a string containing a path or an instance of
   :py:class:`pathlib.Path`.
 - ``drop_variables``: can be `None` or an iterable containing the variable
   names to be dropped when reading the data.
@@ -117,7 +119,7 @@ should implement in its interface the following boolean keyword arguments, calle
 - ``decode_coords``
 
 Note: all the supported decoders shall be declared explicitly
-in backend ``open_dataset`` signature.
+in backend ``open_dataset`` signature and adding a ``**kargs`` is not allowed.
 
 These keyword arguments are explicitly defined in Xarray
 :py:func:`~xarray.open_dataset` signature. Xarray will pass them to the
@@ -241,7 +243,7 @@ How to register a backend
 
 Define a new entrypoint in your ``setup.py`` (or ``setup.cfg``) with:
 
-- group: ``xarray.backend``
+- group: ``xarray.backends``
 - name: the name to be passed to :py:meth:`~xarray.open_dataset`  as ``engine``
 - object reference: the reference of the class that you have implemented.
 
@@ -251,9 +253,7 @@ You can declare the entrypoint in ``setup.py`` using the following syntax:
 
     setuptools.setup(
         entry_points={
-            "xarray.backends": [
-                "engine_name=your_package.your_module:YourBackendEntryClass"
-            ],
+            "xarray.backends": ["my_engine=my_package.my_module:MyBackendEntryClass"],
         },
     )
 
@@ -263,18 +263,18 @@ in ``setup.cfg``:
 
     [options.entry_points]
     xarray.backends =
-        engine_name = your_package.your_module:YourBackendEntryClass
+        my_engine = my_package.my_module:MyBackendEntryClass
 
 
 See https://packaging.python.org/specifications/entry-points/#data-model
 for more information
 
-If you are using [Poetry](https://python-poetry.org/) for your build system, you can accomplish the same thing using "plugins". In this case you would need to add the following to your ``pyproject.toml`` file:
+If you are using `Poetry <https://python-poetry.org/>`_ for your build system, you can accomplish the same thing using "plugins". In this case you would need to add the following to your ``pyproject.toml`` file:
 
 .. code-block:: toml
 
     [tool.poetry.plugins."xarray_backends"]
-    "engine_name" = "your_package.your_module:YourBackendEntryClass"
+    "my_engine" = "my_package.my_module:MyBackendEntryClass"
 
 See https://python-poetry.org/docs/pyproject/#plugins for more information on Poetry plugins.
 
@@ -328,6 +328,9 @@ This is an example ``BackendArray`` subclass implementation:
 
 .. code-block:: python
 
+    from xarray.backends import BackendArray
+
+
     class MyBackendArray(BackendArray):
         def __init__(
             self,

xarray/backends/__init__.py

@@ -4,7 +4,7 @@
 formats. They should not be used directly, but rather through Dataset objects.
 """
 from .cfgrib_ import CfGribDataStore
-from .common import AbstractDataStore
+from .common import AbstractDataStore, BackendArray, BackendEntrypoint
 from .file_manager import CachingFileManager, DummyFileManager, FileManager
 from .h5netcdf_ import H5NetCDFStore
 from .memory import InMemoryDataStore
@@ -18,6 +18,8 @@
 
 __all__ = [
     "AbstractDataStore",
+    "BackendArray",
+    "BackendEntrypoint",
     "FileManager",
     "CachingFileManager",
     "CfGribDataStore",