From e1bad5218e567020b703f5145f55b76fe12813d4 Mon Sep 17 00:00:00 2001
From: Peter Hill <peter.hill@york.ac.uk>
Date: Thu, 19 Oct 2023 13:47:34 +0100
Subject: [PATCH] Docs: Add syntax for registering backends in `pyproject.toml`
 (#8331)

Uses `sphinx-inline-tabs` for pretty and compact options.

Also reword surrounding text a little for clarity, and make examples
consistent with entry point class example
---
 ci/requirements/doc.yml                  |  1 +
 doc/conf.py                              |  1 +
 doc/internals/how-to-add-new-backend.rst | 58 +++++++++++++++---------
 3 files changed, 39 insertions(+), 21 deletions(-)

diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml
index bc35d0db894..e3fb262c437 100644
--- a/ci/requirements/doc.yml
+++ b/ci/requirements/doc.yml
@@ -34,6 +34,7 @@ dependencies:
   - sphinx-book-theme >= 0.3.0
   - sphinx-copybutton
   - sphinx-design
+  - sphinx-inline-tabs
   - sphinx>=5.0
   - zarr>=2.10
   - pip:
diff --git a/doc/conf.py b/doc/conf.py
index d2f6cdf3aa1..74c41b52ab6 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -84,6 +84,7 @@
     "sphinx_copybutton",
     "sphinxext.rediraffe",
     "sphinx_design",
+    "sphinx_inline_tabs",
 ]
 
 
diff --git a/doc/internals/how-to-add-new-backend.rst b/doc/internals/how-to-add-new-backend.rst
index a106232958e..ca42d60abaf 100644
--- a/doc/internals/how-to-add-new-backend.rst
+++ b/doc/internals/how-to-add-new-backend.rst
@@ -9,7 +9,8 @@ to integrate any code in Xarray; all you need to do is:
 - Create a class that inherits from Xarray :py:class:`~xarray.backends.BackendEntrypoint`
   and implements the method ``open_dataset`` see :ref:`RST backend_entrypoint`
 
-- Declare this class as an external plugin in your ``setup.py``, see :ref:`RST backend_registration`
+- Declare this class as an external plugin in your project configuration, see :ref:`RST
+  backend_registration`
 
 If you also want to support lazy loading and dask see :ref:`RST lazy_loading`.
 
@@ -267,42 +268,57 @@ interface only the boolean keywords related to the supported decoders.
 How to register a backend
 +++++++++++++++++++++++++
 
-Define a new entrypoint in your ``setup.py`` (or ``setup.cfg``) with:
+Define a new entrypoint in your ``pyproject.toml`` (or ``setup.cfg/setup.py`` for older
+configurations), with:
 
 - 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.
 
-You can declare the entrypoint in ``setup.py`` using the following syntax:
+You can declare the entrypoint in your project configuration like so:
 
-.. code-block::
+.. tab:: pyproject.toml
 
-    setuptools.setup(
-        entry_points={
-            "xarray.backends": ["my_engine=my_package.my_module:MyBackendEntryClass"],
-        },
-    )
+   .. code:: toml
+
+      [project.entry-points."xarray-backends"]
+      my_engine = "my_package.my_module:MyBackendEntrypoint"
+
+.. tab:: pyproject.toml [Poetry]
+
+   .. code-block:: toml
+
+       [tool.poetry.plugins."xarray.backends"]
+       my_engine = "my_package.my_module:MyBackendEntrypoint"
 
-in ``setup.cfg``:
+.. tab:: setup.cfg
 
-.. code-block:: cfg
+   .. code-block:: cfg
 
-    [options.entry_points]
-    xarray.backends =
-        my_engine = my_package.my_module:MyBackendEntryClass
+       [options.entry_points]
+       xarray.backends =
+           my_engine = my_package.my_module:MyBackendEntrypoint
 
+.. tab:: setup.py
 
-See https://packaging.python.org/specifications/entry-points/#data-model
-for more information
+   .. code-block::
 
-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:
+       setuptools.setup(
+           entry_points={
+               "xarray.backends": [
+                   "my_engine=my_package.my_module:MyBackendEntrypoint"
+               ],
+           },
+       )
 
-.. code-block:: toml
 
-    [tool.poetry.plugins."xarray.backends"]
-    "my_engine" = "my_package.my_module:MyBackendEntryClass"
+See the `Python Packaging User Guide
+<https://packaging.python.org/specifications/entry-points/#data-model>`_ for more
+information on entrypoints and details of the syntax.
 
-See https://python-poetry.org/docs/pyproject/#plugins for more information on Poetry plugins.
+If you're using Poetry, note that table name in ``pyproject.toml`` is slightly different.
+See `the Poetry docs <https://python-poetry.org/docs/pyproject/#plugins>`_ for more
+information on plugins.
 
 .. _RST lazy_loading: