Switch backend API to v2 (#4989)

* Switch backend API to v2 and drop v1

* Remove APIv1 functions now unused

* Clean up imports

* Fix code style

* fix open_dataset documentation

* fix open_dataarray doc

* Remove stale test on removed functions

* Fix entry point definition

* Fix API documentation errors.

* Add informative error message when using positional arguments

* Add `*args` check to `open_dataarray` as well

* Add whats-new entries

Co-authored-by: Aureliana Barghini <a.barghini@bopen.eu>

Author: alexamici

.github/workflows/ci-additional.yaml

@@ -42,7 +42,6 @@ jobs:
             "py37-min-all-deps",
             "py37-min-nep18",
             "py38-all-but-dask",
-            "py38-backend-api-v2",
             "py38-flaky",
           ]
     steps:
@@ -56,12 +55,7 @@ jobs:
 
       - name: Set environment variables
         run: |
-          if [[ ${{ matrix.env }} == "py38-backend-api-v2" ]] ;
-          then
-            echo "CONDA_ENV_FILE=ci/requirements/environment.yml" >> $GITHUB_ENV
-            echo "XARRAY_BACKEND_API=v2" >> $GITHUB_ENV
-
-          elif [[ ${{ matrix.env }} == "py38-flaky" ]] ;
+          if [[ ${{ matrix.env }} == "py38-flaky" ]] ;
           then
             echo "CONDA_ENV_FILE=ci/requirements/environment.yml" >> $GITHUB_ENV
             echo "PYTEST_EXTRA_FLAGS=--run-flaky --run-network-tests" >> $GITHUB_ENV

doc/internals.rst

@@ -249,6 +249,7 @@ re-open it directly with Zarr:
     print(zgroup.tree())
     dict(zgroup["Tair"].attrs)
 
+.. _add_a_backend:
 
 How to add a new backend
 ------------------------

doc/whats-new.rst

@@ -27,22 +27,34 @@ New Features
 - Support for `dask.graph_manipulation
   <https://docs.dask.org/en/latest/graph_manipulation.html>`_ (requires dask >=2021.3)
   By `Guido Imperiale <https://github.com/crusaderky>`_
+- Thanks to the new pluggable backend infrastructure external packages may now
+  use the ``xarray.backends`` entry point to register additional engines to be used in
+  :py:func:`open_dataset`, see the documentation in :ref:`add_a_backend`
+  (:issue:`4309`, :issue:`4803`, :pull:`4989`, :pull:`4810` and many others).
+  The backend refactor has been sponsored with the "Essential Open Source Software for Science"
+  grant from the `Chan Zuckerberg Initiative <https://chanzuckerberg.com>`_ and
+  developed by `B-Open <https://www.bopen.eu>`_.
+  By `Aureliana Barghini <https://github.com/aurghs>`_ and `Alessandro Amici <https://github.com/alexamici>`_.
 
 Breaking changes
 ~~~~~~~~~~~~~~~~
-
+- :py:func:`open_dataset` and :py:func:`open_dataarray` now accept only the first argument
+  as positional, all others need to be passed are keyword arguments. This is part of the
+  refactor to support external backends (:issue:`4309`, :pull:`4989`).
+  By `Alessandro Amici <https://github.com/alexamici>`_.
 
 Deprecations
 ~~~~~~~~~~~~
 
-
 Bug fixes
 ~~~~~~~~~
 - Don't allow passing ``axis`` to :py:meth:`Dataset.reduce` methods (:issue:`3510`, :pull:`4940`).
   By `Justus Magin <https://github.com/keewis>`_.
 
 Documentation
 ~~~~~~~~~~~~~
+- New section on :ref:`add_a_backend` in the "Internals" chapter aimed to backend developers
+  (:issue:`4803`, :pull:`4810`). By `Aureliana Barghini <https://github.com/aurghs>`_.
 
 
 Internal Changes