Automatically generate API reference docs (#1918)

* Automatically generate API reference * Remove old automodapi refs * Fix some doc warnings * Skip private modules * Skip all private objects * Add API ref page for zarr namespace * Fix import errors with zarr.v2 * Remove old numpydoc validation * Use groupwise member order --------- Co-authored-by: Davis Bennett <davis.v.bennett@gmail.com>
zarr-developers · Jun 24, 2024 · 11a959a · 11a959a
1 parent ea6b441
commit 11a959a
Show file tree

Hide file tree

Showing 20 changed files with 48 additions and 229 deletions.
diff --git a/.gitignore b/.gitignore
@@ -51,7 +51,6 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
-docs/_autoapi/
 
 # PyBuilder
 target/

diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/api/attrs.rst b/docs/api/attrs.rst
diff --git a/docs/api/codecs.rst b/docs/api/codecs.rst
diff --git a/docs/api/convenience.rst b/docs/api/convenience.rst
diff --git a/docs/api/core.rst b/docs/api/core.rst
diff --git a/docs/api/creation.rst b/docs/api/creation.rst
diff --git a/docs/api/hierarchy.rst b/docs/api/hierarchy.rst
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 1
+
+    zarr
diff --git a/docs/api/n5.rst b/docs/api/n5.rst
diff --git a/docs/api/storage.rst b/docs/api/storage.rst
diff --git a/docs/api/sync.rst b/docs/api/sync.rst
diff --git a/docs/api/zarr.rst b/docs/api/zarr.rst
@@ -0,0 +1,5 @@
+zarr
+====
+
+.. autoapimodule:: zarr
+    :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,13 +15,17 @@
 
 import os
 import sys
+from typing import Any
+
+import sphinx.application
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
 import zarr
+import sphinx
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -42,19 +46,21 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
-    "sphinx_automodapi.automodapi",
+    'autoapi.extension',
     "numpydoc",
     "sphinx_issues",
     "sphinx_copybutton",
     "sphinx_design",
 ]
 
-numpydoc_show_class_members = False
-numpydoc_class_members_toctree = False
 issues_github_path = "zarr-developers/zarr-python"
 
-automodapi_inheritance_diagram = False
-automodapi_toctreedirnm = "_autoapi"
+autoapi_dirs = ['../src/zarr']
+autoapi_add_toctree_entry = False
+autoapi_generate_api_docs = False
+autoapi_member_order = "groupwise"
+autoapi_root = "api"
+
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -166,8 +172,7 @@
 html_logo = "_static/logo1.png"
 
 
-# Add custom css
-def setup(app):
+def setup(app: sphinx.application.Sphinx) -> None:
     app.add_css_file("custom.css")
 
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -10,7 +10,7 @@ Zarr-Python
 
     getting_started
     tutorial
-    api
+    api/index
     spec
     release
     license
@@ -80,7 +80,7 @@ Zarr is a file storage format for chunked, compressed, N-dimensional arrays base
 
         +++
 
-        .. button-ref:: api
+        .. button-ref:: api/index
             :expand:
             :color: dark
             :click-parent:

diff --git a/pyproject.toml b/pyproject.toml
@@ -63,7 +63,7 @@ jupyter = [
 docs = [
     'sphinx',
     'sphinx-autobuild>=2021.3.14',
-    'sphinx-automodapi',
+    'sphinx-autoapi',
     'sphinx_design',
     'sphinx-issues',
     'sphinx-copybutton',
@@ -146,7 +146,7 @@ features = ['docs']
 
 [tool.hatch.envs.docs.scripts]
 build = "cd docs && make html"
-serve = "sphinx-autobuild docs docs/_build --ignore 'docs/_autoapi/**/*' --host 0.0.0.0"
+serve = "sphinx-autobuild docs docs/_build --host 0.0.0.0"
 
 [tool.ruff]
 line-length = 100