Autogenerate all API docs

.gitignore

@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_autoapi
 
 # PyBuilder
 target/

docs/Makefile

@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:

docs/api/index.rst

@@ -4,4 +4,4 @@ API Reference
 .. toctree::
  :maxdepth: 1
 
- zarr
+../_autoapi/zarr/index

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_root = "_autoapi"
+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("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
+ 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),
 }

pyproject.toml

@@ -78,9 +78,9 @@ gpu = [
  "cupy-cuda12x",
 ]
 docs = [
- 'sphinx',
+ 'sphinx<8',
  'sphinx-autobuild>=2021.3.14',
- 'sphinx-autoapi',
+ 'sphinx-autoapi<3.1',
  'sphinx_design',
  'sphinx-issues',
  'sphinx-copybutton',

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"

src/zarr/codecs/bytes.py

@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+ """
+ Enum for endian type used by bytes codec.
+ """
+
  big = "big"
  little = "little"
 

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"
 

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):

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):

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
@@ -700,7 +704,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

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)),...]
+ """
+ Function 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)

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

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")))

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

.gitignore

@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_autoapi
 
 # PyBuilder
 target/

docs/Makefile

@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:

docs/api/index.rst

@@ -4,4 +4,4 @@ API Reference
 .. toctree::
  :maxdepth: 1
 
- zarr
+../_autoapi/zarr/index

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_root = "_autoapi"
+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("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
+ 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),
 }

pyproject.toml

@@ -78,9 +78,9 @@ gpu = [
  "cupy-cuda12x",
 ]
 docs = [
- 'sphinx',
+ 'sphinx<8',
  'sphinx-autobuild>=2021.3.14',
- 'sphinx-autoapi',
+ 'sphinx-autoapi<3.1',
  'sphinx_design',
  'sphinx-issues',
  'sphinx-copybutton',

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"

src/zarr/codecs/bytes.py

@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+ """
+ Enum for endian type used by bytes codec.
+ """
+
  big = "big"
  little = "little"
 

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"
 

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):

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):

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
@@ -700,7 +704,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

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)),...]
+ """
+ Function 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)

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

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")))

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

.gitignore

@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_autoapi
 
 # PyBuilder
 target/

docs/Makefile

@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:

docs/api/index.rst

@@ -4,4 +4,4 @@ API Reference
 .. toctree::
  :maxdepth: 1
 
- zarr
+../_autoapi/zarr/index

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_root = "_autoapi"
+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("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
+ 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),
 }

pyproject.toml

@@ -78,9 +78,9 @@ gpu = [
  "cupy-cuda12x",
 ]
 docs = [
- 'sphinx',
+ 'sphinx<8',
  'sphinx-autobuild>=2021.3.14',
- 'sphinx-autoapi',
+ 'sphinx-autoapi<3.1',
  'sphinx_design',
  'sphinx-issues',
  'sphinx-copybutton',

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"

src/zarr/codecs/bytes.py

@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+ """
+ Enum for endian type used by bytes codec.
+ """
+
  big = "big"
  little = "little"
 

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"
 

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):

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):

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
@@ -700,7 +704,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

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)),...]
+ """
+ Function 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)

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

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")))

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

.gitignore

@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_autoapi
 
 # PyBuilder
 target/

docs/Makefile

@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:

docs/api/index.rst

@@ -4,4 +4,4 @@ API Reference
 .. toctree::
  :maxdepth: 1
 
- zarr
+../_autoapi/zarr/index

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_root = "_autoapi"
+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("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
+ 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),
 }

pyproject.toml

@@ -78,9 +78,9 @@ gpu = [
  "cupy-cuda12x",
 ]
 docs = [
- 'sphinx',
+ 'sphinx<8',
  'sphinx-autobuild>=2021.3.14',
- 'sphinx-autoapi',
+ 'sphinx-autoapi<3.1',
  'sphinx_design',
  'sphinx-issues',
  'sphinx-copybutton',

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"

src/zarr/codecs/bytes.py

@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+ """
+ Enum for endian type used by bytes codec.
+ """
+
  big = "big"
  little = "little"
 

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"
 

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):

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):

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
@@ -700,7 +704,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

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)),...]
+ """
+ Function 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)

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

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")))

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

.gitignore

@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_autoapi
 
 # PyBuilder
 target/

docs/Makefile

@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:

docs/api/index.rst

@@ -4,4 +4,4 @@ API Reference
 .. toctree::
  :maxdepth: 1
 
- zarr
+../_autoapi/zarr/index

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_root = "_autoapi"
+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("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
+ 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),
 }

pyproject.toml

@@ -78,9 +78,9 @@ gpu = [
  "cupy-cuda12x",
 ]
 docs = [
- 'sphinx',
+ 'sphinx<8',
  'sphinx-autobuild>=2021.3.14',
- 'sphinx-autoapi',
+ 'sphinx-autoapi<3.1',
  'sphinx_design',
  'sphinx-issues',
  'sphinx-copybutton',

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"

src/zarr/codecs/bytes.py

@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+ """
+ Enum for endian type used by bytes codec.
+ """
+
  big = "big"
  little = "little"
 

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"
 

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):

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):

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
@@ -700,7 +704,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

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)),...]
+ """
+ Function 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)

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

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")))

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

.gitignore

@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_autoapi
 
 # PyBuilder
 target/

docs/Makefile

@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:

docs/api/index.rst

@@ -4,4 +4,4 @@ API Reference
 .. toctree::
  :maxdepth: 1
 
- zarr
+../_autoapi/zarr/index

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_root = "_autoapi"
+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("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
+ 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),
 }

pyproject.toml

@@ -78,9 +78,9 @@ gpu = [
  "cupy-cuda12x",
 ]
 docs = [
- 'sphinx',
+ 'sphinx<8',
  'sphinx-autobuild>=2021.3.14',
- 'sphinx-autoapi',
+ 'sphinx-autoapi<3.1',
  'sphinx_design',
  'sphinx-issues',
  'sphinx-copybutton',

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"

src/zarr/codecs/bytes.py

@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+ """
+ Enum for endian type used by bytes codec.
+ """
+
  big = "big"
  little = "little"
 

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"
 

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):

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):

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
@@ -700,7 +704,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

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)),...]
+ """
+ Function 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)

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

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")))

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

.gitignore

@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_autoapi
 
 # PyBuilder
 target/

docs/Makefile

@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:

docs/api/index.rst

@@ -4,4 +4,4 @@ API Reference
 .. toctree::
  :maxdepth: 1
 
- zarr
+../_autoapi/zarr/index

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_root = "_autoapi"
+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("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
+ 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),
 }

pyproject.toml

@@ -78,9 +78,9 @@ gpu = [
  "cupy-cuda12x",
 ]
 docs = [
- 'sphinx',
+ 'sphinx<8',
  'sphinx-autobuild>=2021.3.14',
- 'sphinx-autoapi',
+ 'sphinx-autoapi<3.1',
  'sphinx_design',
  'sphinx-issues',
  'sphinx-copybutton',

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"

src/zarr/codecs/bytes.py

@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+ """
+ Enum for endian type used by bytes codec.
+ """
+
  big = "big"
  little = "little"
 

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"
 

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):

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):

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
@@ -700,7 +704,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

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)),...]
+ """
+ Function 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)

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

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")))

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

.gitignore

@@ -51,6 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_autoapi
 
 # PyBuilder
 target/

docs/Makefile

@@ -52,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/../_autoapi
 
 .PHONY: html
 html:

docs/api/index.rst

@@ -4,4 +4,4 @@ API Reference
 .. toctree::
  :maxdepth: 1
 
- zarr
+../_autoapi/zarr/index

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_root = "_autoapi"
+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("_") for part in parts) or "v2" in name or name.startswith("zarr.core")):
+ 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),
 }

pyproject.toml

@@ -78,9 +78,9 @@ gpu = [
  "cupy-cuda12x",
 ]
 docs = [
- 'sphinx',
+ 'sphinx<8',
  'sphinx-autobuild>=2021.3.14',
- 'sphinx-autoapi',
+ 'sphinx-autoapi<3.1',
  'sphinx_design',
  'sphinx-issues',
  'sphinx-copybutton',

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"

src/zarr/codecs/bytes.py

@@ -19,6 +19,10 @@
 
 
 class Endian(Enum):
+ """
+ Enum for endian type used by bytes codec.
+ """
+
  big = "big"
  little = "little"
 

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"
 

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):

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):

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
@@ -700,7 +704,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

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)),...]
+ """
+ Function 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)

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

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")))

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