Autogenerate all API docs (#2002)

* Autogenerate all API docs

* Fix duplicate Array docs

* Fix doc errors

* Fix skip logic

* Fix module name splitting

* Change autoapi directory

* Add more enum docs

* Fix testing docstring

* Pin max version of sphinx-autoapi

* Fix spelling

* Pin max version of sphinx-autoapi

* Skip zarr.core in API docs

* Fix buffer namespace

.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