From ed0f199e8542b410ae655c8168a49a0be6237cd4 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Sun, 8 Dec 2024 23:18:01 +0000
Subject: [PATCH] Improve installation page (#2538)

* Make code blocks console

* Clean up installation page

* Split into pip/conda

* Fix doc headings

* Fix contributing link

* Fix contributing link
---
 docs/installation.rst  | 38 ++++++++++++++++++++++++--------------
 src/zarr/core/group.py | 13 +++++++------
 2 files changed, 31 insertions(+), 20 deletions(-)

diff --git a/docs/installation.rst b/docs/installation.rst
index 86da6d1035..b39b54b250 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,27 +1,37 @@
 Installation
 ============
 
-Zarr depends on NumPy. It is generally best to `install NumPy
-<https://numpy.org/doc/stable/user/install.html>`_ first using whatever method is most
-appropriate for your operating system and Python distribution. Other dependencies should be
-installed automatically if using one of the installation methods below.
+pip
+---
 
-Note: Zarr has endorsed `Scientific-Python SPEC 0 <https://scientific-python.org/specs/spec-0000/>`_ and now follows the version support window as outlined below: 
+.. code-block:: console
 
-- Python: 36 months after initial release
-- Core package dependencies (e.g. NumPy): 24 months after initial release
+    $ pip install zarr
 
-Install Zarr from PyPI::
+There are a number of optional dependency groups you can install for extra functionality.
+These can be installed using ``pip install "zarr[<extra>]"``, e.g. ``pip install "zarr[gpu]"``
 
-    $ pip install zarr
+- ``gpu``: support for GPUs
+- ``fsspec``: support for reading/writing to remote data stores
+- ``tree``: support for pretty printing of directory trees
 
-Alternatively, install Zarr via conda::
+conda
+-----
+
+.. code-block:: console
 
     $ conda install -c conda-forge zarr
 
-To install the latest development version of Zarr, you can use pip with the
-latest GitHub main::
+Conda does not support optional dependencies, so you will have to manually install any packages
+needed to enable extra functionality.
+
+Dependency support
+------------------
+Zarr has endorsed `Scientific-Python SPEC 0 <https://scientific-python.org/specs/spec-0000/>`_ and now follows the version support window as outlined below:
 
-    $ pip install git+https://github.com/zarr-developers/zarr-python.git
+- Python: 36 months after initial release
+- Core package dependencies (e.g. NumPy): 24 months after initial release
 
-To work with Zarr source code in development, see `Contributing <contributing.html>`_.
\ No newline at end of file
+Development
+-----------
+To install the latest development version of Zarr, see `the contributing guide <contributing.html>`_.
diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py
index adc6399276..3613e3e12b 100644
--- a/src/zarr/core/group.py
+++ b/src/zarr/core/group.py
@@ -1847,8 +1847,8 @@ def __repr__(self) -> str:
     async def update_attributes_async(self, new_attributes: dict[str, Any]) -> Group:
         """Update the attributes of this group.
 
-        Example
-        -------
+        Examples
+        --------
         >>> import zarr
         >>> group = zarr.group()
         >>> await group.update_attributes_async({"foo": "bar"})
@@ -1947,8 +1947,9 @@ def synchronizer(self) -> None:
 
     def update_attributes(self, new_attributes: dict[str, Any]) -> Group:
         """Update the attributes of this group.
-        Example
-        -------
+
+        Examples
+        --------
         >>> import zarr
         >>> group = zarr.group()
         >>> group.update_attributes({"foo": "bar"})
@@ -2027,8 +2028,8 @@ def __contains__(self, member: str) -> bool:
     def groups(self) -> Generator[tuple[str, Group], None]:
         """Return the sub-groups of this group as a generator of (name, group) pairs.
 
-        Example
-        -------
+        Examples
+        --------
         >>> import zarr
         >>> group = zarr.group()
         >>> group.create_group("subgroup")