From 95a90a6e55d02d03d7c96cca7410085a4a909971 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Fri, 28 Jun 2024 08:15:59 +0100
Subject: [PATCH 01/13] Autogenerate all API docs

---
 .gitignore         |  1 +
 docs/api/index.rst |  2 +-
 docs/api/zarr.rst  |  5 -----
 docs/conf.py       | 16 ++++++++++++++--
 4 files changed, 16 insertions(+), 8 deletions(-)
 delete mode 100644 docs/api/zarr.rst

diff --git a/.gitignore b/.gitignore
index 84bcb00ffb..557b5f1e26 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/api/zarr
 
 # PyBuilder
 target/
diff --git a/docs/api/index.rst b/docs/api/index.rst
index 58ea531905..1fbeca479c 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -4,4 +4,4 @@ API Reference
 .. toctree::
     :maxdepth: 1
 
-    zarr
+    zarr/index
diff --git a/docs/api/zarr.rst b/docs/api/zarr.rst
deleted file mode 100644
index 8a9216f19e..0000000000
--- a/docs/api/zarr.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-zarr
-====
-
-.. autoapimodule:: zarr
-    :members:
diff --git a/docs/conf.py b/docs/conf.py
index 35afa60577..c678d7aecc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -57,9 +57,10 @@
 
 autoapi_dirs = ['../src/zarr']
 autoapi_add_toctree_entry = False
-autoapi_generate_api_docs = False
+autoapi_generate_api_docs = True
 autoapi_member_order = "groupwise"
 autoapi_root = "api"
+autoapi_keep_files = True
 
 
 # Add any paths that contain templates here, relative to this directory.
@@ -172,8 +173,19 @@
 html_logo = "_static/logo1.png"
 
 
+def autoapi_skip_modules(app: sphinx.application.Sphinx, what: str, name: str, obj: object, skip: bool, options: dict[str, Any]) -> bool:
+    """
+    Return True if a module should be skipped in th API docs.
+    """
+    parts = name.split("_")
+    if what == "module" and any(part.startswith("_") or part == "v2" for part in parts):
+        return True
+    return False
+
+
 def setup(app: sphinx.application.Sphinx) -> None:
     app.add_css_file("custom.css")
+    app.connect("autoapi-skip-member", autoapi_skip_modules)
 
 
 # The name of an image file (relative to this directory) to use as a favicon of
@@ -339,7 +351,7 @@ def setup(app: sphinx.application.Sphinx) -> None:
 # use in refs e.g:
 # :ref:`comparison manual <python:comparisons>`
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/", None),
+    "python": ("https://docs.python.org/3/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "numcodecs": ("https://numcodecs.readthedocs.io/en/stable/", None),
 }

From 7df572b3b04584dc627d93d2a181058a9c845069 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Fri, 28 Jun 2024 08:16:16 +0100
Subject: [PATCH 02/13] Fix duplicate Array docs

---
 src/zarr/core/array.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py
index fbe0b19f6b..dcd7217d7d 100644
--- a/src/zarr/core/array.py
+++ b/src/zarr/core/array.py
@@ -68,6 +68,9 @@
 
     from zarr.abc.codec import Codec, CodecPipeline
 
+# Array and AsyncArray are defined in the base ``zarr`` namespace
+__all__ = ["parse_array_metadata", "create_codec_pipeline"]
+
 
 def parse_array_metadata(data: Any) -> ArrayV2Metadata | ArrayV3Metadata:
     if isinstance(data, ArrayV2Metadata | ArrayV3Metadata):

From ed72dbc6bcbbc044c00af8f5e1a1689c1682e721 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Fri, 28 Jun 2024 08:22:38 +0100
Subject: [PATCH 03/13] Fix doc errors

---
 src/zarr/core/indexing.py | 2 +-
 src/zarr/v2/indexing.py   | 2 +-
 src/zarr/v2/meta.py       | 3 +--
 src/zarr/v2/n5.py         | 1 +
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/zarr/core/indexing.py b/src/zarr/core/indexing.py
index e6e04e58f6..0bc8b68d5b 100644
--- a/src/zarr/core/indexing.py
+++ b/src/zarr/core/indexing.py
@@ -700,7 +700,7 @@ def slice_to_range(s: slice, length: int) -> range:
 
 
 def ix_(selection: Any, shape: ChunkCoords) -> npt.NDArray[np.intp]:
-    """Convert an orthogonal selection to a numpy advanced (fancy) selection, like numpy.ix_
+    """Convert an orthogonal selection to a numpy advanced (fancy) selection, like ``numpy.ix_``
     but with support for slices and single ints."""
 
     # normalisation
diff --git a/src/zarr/v2/indexing.py b/src/zarr/v2/indexing.py
index bb2d9f1adb..880baf3f72 100644
--- a/src/zarr/v2/indexing.py
+++ b/src/zarr/v2/indexing.py
@@ -534,7 +534,7 @@ def slice_to_range(s: slice, l: int):  # noqa: E741
 
 
 def ix_(selection, shape):
-    """Convert an orthogonal selection to a numpy advanced (fancy) selection, like numpy.ix_
+    """Convert an orthogonal selection to a numpy advanced (fancy) selection, like ``numpy.ix_``
     but with support for slices and single ints."""
 
     # normalisation
diff --git a/src/zarr/v2/meta.py b/src/zarr/v2/meta.py
index 418c0727cf..2f7ce1242e 100644
--- a/src/zarr/v2/meta.py
+++ b/src/zarr/v2/meta.py
@@ -17,8 +17,7 @@
 
 # FLOAT_FILLS = {"NaN": np.nan, "Infinity": np.PINF, "-Infinity": np.NINF}
 
-_v3_core_types = set("".join(d) for d in itertools.product("<>", ("u", "i", "f"), ("2", "4", "8")))
-_v3_core_types = {"bool", "i1", "u1"} | _v3_core_types
+_v3_core_types = {"bool", "i1", "u1"} | set("".join(d) for d in itertools.product("<>", ("u", "i", "f"), ("2", "4", "8")))
 
 # The set of complex types allowed ({"<c8", "<c16", ">c8", ">c16"})
 _v3_complex_types = set(f"{end}c{_bytes}" for end, _bytes in itertools.product("<>", ("8", "16")))
diff --git a/src/zarr/v2/n5.py b/src/zarr/v2/n5.py
index a6fd39f5b8..ece110f49d 100644
--- a/src/zarr/v2/n5.py
+++ b/src/zarr/v2/n5.py
@@ -272,6 +272,7 @@ class N5FSStore(FSStore):
     """Implementation of the N5 format (https://github.com/saalfeldlab/n5)
     using `fsspec`, which allows storage on a variety of filesystems. Based
     on `zarr.N5Store`.
+
     Parameters
     ----------
     path : string

From daa7be39439fb93acf5f8e3233c199aeadafef55 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Fri, 28 Jun 2024 08:25:56 +0100
Subject: [PATCH 04/13] Fix skip logic

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index c678d7aecc..c757de1f95 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -178,7 +178,7 @@ def autoapi_skip_modules(app: sphinx.application.Sphinx, what: str, name: str, o
     Return True if a module should be skipped in th API docs.
     """
     parts = name.split("_")
-    if what == "module" and any(part.startswith("_") or part == "v2" for part in parts):
+    if what == "module" and any((part.startswith("_") or part == "v2") for part in parts):
         return True
     return False
 

From 22e4936106c46aca7dbcec8b8689c9395bbe039d Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Fri, 28 Jun 2024 08:28:26 +0100
Subject: [PATCH 05/13] Fix module name splitting

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index c757de1f95..19b825e9b2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -177,7 +177,7 @@ def autoapi_skip_modules(app: sphinx.application.Sphinx, what: str, name: str, o
     """
     Return True if a module should be skipped in th API docs.
     """
-    parts = name.split("_")
+    parts = name.split(".")
     if what == "module" and any((part.startswith("_") or part == "v2") for part in parts):
         return True
     return False

From 719399cbe2fbf4aad9985272f21a82edf94a8332 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Tue, 20 Aug 2024 19:17:24 +0100
Subject: [PATCH 06/13] Change autoapi directory

---
 .gitignore         | 2 +-
 docs/Makefile      | 1 +
 docs/api/index.rst | 2 +-
 docs/conf.py       | 2 +-
 4 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 557b5f1e26..a09fb54d5c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,7 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
-docs/api/zarr
+docs/_autoapi
 
 # PyBuilder
 target/
diff --git a/docs/Makefile b/docs/Makefile
index e6adc1ca8c..fc8fa12915 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:
diff --git a/docs/api/index.rst b/docs/api/index.rst
index 1fbeca479c..8735180cd9 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -4,4 +4,4 @@ API Reference
 .. toctree::
     :maxdepth: 1
 
-    zarr/index
+    ../_autoapi/zarr/index
diff --git a/docs/conf.py b/docs/conf.py
index 19b825e9b2..f8de02cae4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -59,7 +59,7 @@
 autoapi_add_toctree_entry = False
 autoapi_generate_api_docs = True
 autoapi_member_order = "groupwise"
-autoapi_root = "api"
+autoapi_root = "_autoapi"
 autoapi_keep_files = True
 
 

From 64c13558a37ab978e07a4352c90f07dbb728f9b6 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Tue, 20 Aug 2024 19:17:31 +0100
Subject: [PATCH 07/13] Add more enum docs

---
 src/zarr/codecs/blosc.py    | 8 ++++++++
 src/zarr/codecs/bytes.py    | 4 ++++
 src/zarr/codecs/sharding.py | 4 ++++
 src/zarr/core/indexing.py   | 4 ++++
 4 files changed, 20 insertions(+)

diff --git a/src/zarr/codecs/blosc.py b/src/zarr/codecs/blosc.py
index cd265e3dc0..f831dc960d 100644
--- a/src/zarr/codecs/blosc.py
+++ b/src/zarr/codecs/blosc.py
@@ -21,6 +21,10 @@
 
 
 class BloscShuffle(Enum):
+    """
+    Enum for shuffle filter used by blosc.
+    """
+
     noshuffle = "noshuffle"
     shuffle = "shuffle"
     bitshuffle = "bitshuffle"
@@ -38,6 +42,10 @@ def from_int(cls, num: int) -> BloscShuffle:
 
 
 class BloscCname(Enum):
+    """
+    Enum for compression library used by blosc.
+    """
+
     lz4 = "lz4"
     lz4hc = "lz4hc"
     blosclz = "blosclz"
diff --git a/src/zarr/codecs/bytes.py b/src/zarr/codecs/bytes.py
index 4561b22346..bc3207be2e 100644
--- a/src/zarr/codecs/bytes.py
+++ b/src/zarr/codecs/bytes.py
@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+    """
+    Enum for endian type used by bytes codec.
+    """
+
     big = "big"
     little = "little"
 
diff --git a/src/zarr/codecs/sharding.py b/src/zarr/codecs/sharding.py
index 9eb8e2ffb3..5281104724 100644
--- a/src/zarr/codecs/sharding.py
+++ b/src/zarr/codecs/sharding.py
@@ -60,6 +60,10 @@
 
 
 class ShardingCodecIndexLocation(Enum):
+    """
+    Enum for index location used by the sharding codec.
+    """
+
     start = "start"
     end = "end"
 
diff --git a/src/zarr/core/indexing.py b/src/zarr/core/indexing.py
index 0bc8b68d5b..caf57e212a 100644
--- a/src/zarr/core/indexing.py
+++ b/src/zarr/core/indexing.py
@@ -559,6 +559,10 @@ def __iter__(self) -> Iterator[ChunkDimProjection]:
 
 
 class Order(Enum):
+    """
+    Enum for indexing order.
+    """
+
     UNKNOWN = 0
     INCREASING = 1
     DECREASING = 2

From 36601fb4e5d735226fdfbc396a34ef7f1ac4d922 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Tue, 20 Aug 2024 19:20:23 +0100
Subject: [PATCH 08/13] Fix testing docstring

---
 src/zarr/testing/strategies.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/zarr/testing/strategies.py b/src/zarr/testing/strategies.py
index 3a460d4fff..882b11423a 100644
--- a/src/zarr/testing/strategies.py
+++ b/src/zarr/testing/strategies.py
@@ -155,9 +155,12 @@ def basic_indices(draw: st.DrawFn, *, shape: tuple[int], **kwargs):  # type: ign
 
 
 def key_ranges(keys: SearchStrategy = node_names) -> SearchStrategy[list]:
-    """fn to generate key_ranges strategy for get_partial_values()
-    returns list strategy w/ form: [(key, (range_start, range_step)),
-                                    (key, (range_start, range_step)),...]
+    """
+    Funciton to generate key_ranges strategy for get_partial_values()
+    returns list strategy w/ form::
+
+        [(key, (range_start, range_step)),
+         (key, (range_start, range_step)),...]
     """
     byte_ranges = st.tuples(
         st.none() | st.integers(min_value=0), st.none() | st.integers(min_value=0)

From 263b4876ab989c15a80a64213fce09e3a9dee6d4 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Tue, 20 Aug 2024 19:29:53 +0100
Subject: [PATCH 09/13] Pin max version of sphinx-autoapi

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index c6ab4a4638..f34f171209 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -80,7 +80,7 @@ gpu = [
 docs = [
     'sphinx',
     'sphinx-autobuild>=2021.3.14',
-    'sphinx-autoapi',
+    'sphinx-autoapi<3.2',
     'sphinx_design',
     'sphinx-issues',
     'sphinx-copybutton',

From 200c77e69436c7ea4797c3d4a7c259b2ab9bcd46 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Tue, 20 Aug 2024 19:31:37 +0100
Subject: [PATCH 10/13] Fix spelling

---
 src/zarr/testing/strategies.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/zarr/testing/strategies.py b/src/zarr/testing/strategies.py
index 882b11423a..83de3d92ce 100644
--- a/src/zarr/testing/strategies.py
+++ b/src/zarr/testing/strategies.py
@@ -156,7 +156,7 @@ def basic_indices(draw: st.DrawFn, *, shape: tuple[int], **kwargs):  # type: ign
 
 def key_ranges(keys: SearchStrategy = node_names) -> SearchStrategy[list]:
     """
-    Funciton to generate key_ranges strategy for get_partial_values()
+    Function to generate key_ranges strategy for get_partial_values()
     returns list strategy w/ form::
 
         [(key, (range_start, range_step)),

From 80f35e0eee1817636396484bc620e84eba1c62c2 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Tue, 20 Aug 2024 19:34:24 +0100
Subject: [PATCH 11/13] Pin max version of sphinx-autoapi

---
 pyproject.toml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index f34f171209..da0763d093 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -78,9 +78,9 @@ gpu = [
     "cupy-cuda12x",
 ]
 docs = [
-    'sphinx',
+    'sphinx<8',
     'sphinx-autobuild>=2021.3.14',
-    'sphinx-autoapi<3.2',
+    'sphinx-autoapi<3.1',
     'sphinx_design',
     'sphinx-issues',
     'sphinx-copybutton',

From e46d310ace2e2a63ec69e17fd69ef9be27bacfff Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Tue, 27 Aug 2024 19:05:13 +0100
Subject: [PATCH 12/13] Skip zarr.core in API docs

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index f8de02cae4..c2805d6239 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -178,7 +178,7 @@ def autoapi_skip_modules(app: sphinx.application.Sphinx, what: str, name: str, o
     Return True if a module should be skipped in th API docs.
     """
     parts = name.split(".")
-    if what == "module" and any((part.startswith("_") or part == "v2") for part in parts):
+    if what == "module" and (any(part.startswith("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
         return True
     return False
 

From fb43c15034a4e43544f0e878b64670a0351aa840 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Sun, 8 Sep 2024 10:04:20 +0100
Subject: [PATCH 13/13] Fix buffer namespace

---
 src/zarr/core/buffer/core.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/zarr/core/buffer/core.py b/src/zarr/core/buffer/core.py
index fca2da2b77..6aff47e8d3 100644
--- a/src/zarr/core/buffer/core.py
+++ b/src/zarr/core/buffer/core.py
@@ -29,6 +29,9 @@
     from zarr.codecs.bytes import Endian
     from zarr.core.common import BytesLike, ChunkCoords
 
+# Everything here is imported into ``zarr.core.buffer`` namespace.
+__all__: list[str] = []
+
 
 @runtime_checkable
 class ArrayLike(Protocol):