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

Author: dstansby

.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/api/zarr.rst

@@ -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),
 }

docs/conf.py

@@ -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',

pyproject.toml

@@ -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/blosc.py

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

src/zarr/codecs/bytes.py

@@ -60,6 +60,10 @@
 
 
 class ShardingCodecIndexLocation(Enum):
+    """
+    Enum for index location used by the sharding codec.
+    """
+
     start = "start"
     end = "end"
 

src/zarr/codecs/sharding.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):