Fix autosummary by patching stub sub-modules in conf.py

Author: honno

spec/2021.12/conf.py

@@ -0,0 +1,7 @@
+import sys
+
+from array_api_stubs import _2021_12 as stubs_mod
+from _spec_conf import *
+
+release = "2021.12"
+sys.modules["signatures"] = stubs_mod

spec/Makefile

@@ -21,5 +21,4 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)
-	-rm -rf "$(SOURCEDIR)/draft/API_specification/generated"
-	-rm -rf "$(SOURCEDIR)/draft/extensions/generated"
+	-rm -rf $(SOURCEDIR)/**/generated

spec/draft/conf.py

@@ -0,0 +1,7 @@
+import sys
+
+from array_api_stubs import _draft as stubs_mod
+from _spec_conf import *
+
+release = "DRAFT"
+sys.modules["array_api"] = stubs_mod

spec/conf.py src/_spec_conf.pyspec/conf.py renamed to src/_spec_conf.py

@@ -1,30 +1,18 @@
-# Configuration file for the Sphinx documentation builder.
+# Base configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+import re
 
-# -- Path setup --------------------------------------------------------------
-
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import os
-import sys
 import sphinx_material
-import array_api_stubs
 
 # -- Project information -----------------------------------------------------
 
 project = 'Python array API standard'
 copyright = '2020, Consortium for Python Data API Standards'
 author = 'Consortium for Python Data API Standards'
 
-# The full version, including alpha/beta/rc tags
-release = '2022.05-DRAFT'
-
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -64,23 +52,23 @@
 # autodoc wants to make cross-references for every type hint. But a lot of
 # them don't actually refer to anything that we have a document for.
 nitpick_ignore = [
-    ('py:class', 'device'),
-    ('py:class', 'dtype'),
-    ('py:class', 'NestedSequence'),
-    ('py:class', 'SupportsBufferProtocol'),
     ('py:class', 'collections.abc.Sequence'),
     ('py:class', "Optional[Union[int, float, Literal[inf, - inf, 'fro', 'nuc']]]"),
     ('py:class', "Union[int, float, Literal[inf, - inf]]"),
     ('py:obj', "typing.Optional[typing.Union[int, float, typing.Literal[inf, - inf, 'fro', 'nuc']]]"),
     ('py:obj', "typing.Union[int, float, typing.Literal[inf, - inf]]"),
-    ('py:class', 'PyCapsule'),
     ('py:class', 'enum.Enum'),
     ('py:class', 'ellipsis'),
-    ('py:class', 'finfo_object'),
-    ('py:class', 'iinfo_object'),
 ]
 nitpick_ignore_regex = [
     ('py:class', '.*array'),
+    ('py:class', '.*device'),
+    ('py:class', '.*dtype'),
+    ('py:class', '.*NestedSequence'),
+    ('py:class', '.*SupportsBufferProtocol'),
+    ('py:class', '.*PyCapsule'),
+    ('py:class', '.*finfo_object'),
+    ('py:class', '.*iinfo_object'),
 ]
 # In array_object.py we have to use aliased names for some types because they
 # would otherwise refer back to method objects of array
@@ -101,7 +89,7 @@
 autosummary_mod.mangle_signature = lambda sig, max_chars=30: sig
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['../_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -125,7 +113,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['../_static']
 
 
 # -- Material theme options (see theme.conf for more information) ------------
@@ -137,7 +125,7 @@
 html_theme_options = {
 
     # Set the name of the project to appear in the navigation.
-    'nav_title': f'Python array API standard {release}',
+    'nav_title': f'Python array API standard',
 
     # Set you GA account ID to enable tracking
     #'google_analytics_account': 'UA-XXXXX',
@@ -206,12 +194,14 @@
     "pypa": ("https://packaging.python.org/%s", ""),
 }
 
+# -- Prettify type hints -----------------------------------------------------
+r_type_prefix = re.compile(r"array_api_stubs\._[a-z0-9_]+\._types\.")
 
 def process_signature(app, what, name, obj, options, signature, return_annotation):
     if signature:
-        signature = signature.replace("array_api._types.", "")
+        signature = re.sub(r_type_prefix, "", signature)
     if return_annotation:
-        return_annotation = return_annotation.replace("array_api._types.", "")
+        return_annotation = re.sub(r_type_prefix, "", return_annotation)
     return signature, return_annotation
 
 def setup(app):

src/array_api_stubs/__init__.py

@@ -1,2 +1,2 @@
-from . import draft
+from . import _2021_12, _draft