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

Author: honno

spec/2021.12/API_specification/data_types.rst

@@ -77,6 +77,15 @@ Double-precision (128-bit) complex floating-point number whose real and imaginar
 
    Accordingly, subnormal behavior is left unspecified and, thus, implementation-defined. Conforming implementations may vary in their support for subnormal numbers.
 
+.. admonition:: Future extension
+   :class: admonition tip
+
+   ``complex64`` and ``complex128`` data types are expected to be included in the next version of this standard and to have the following casting rules (will be added to :ref:`type-promotion`):
+
+   .. image:: ../../_static/images/dtype_promotion_complex.png
+
+   See `array-api/issues/102 <https://github.com/data-apis/array-api/issues/102>`_ for more details
+
 .. note::
    A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification.
 

spec/2021.12/API_specification/type_promotion.rst

@@ -7,7 +7,7 @@ Type Promotion Rules
 
 Type promotion rules can be understood at a high level from the following diagram:
 
-.. image:: /_static/images/dtype_promotion_lattice.png
+.. image:: ../../_static/images/dtype_promotion_lattice.png
     :target: Type promotion diagram
 
 *Type promotion diagram. Promotion between any two types is given by their join on this lattice. Only the types of participating arrays matter, not their values. Dashed lines indicate that behavior for Python scalars is undefined on overflow. Boolean, integer and floating-point dtypes are not connected, indicating mixed-kind promotion is undefined.*

spec/2021.12/assumptions.md

@@ -35,7 +35,7 @@ such a coupling. Facilitation support of multiple array types in downstream
 libraries is an important use case however, the assumed dependency structure
 for that is:
 
-![dependency assumptions diagram](_static/images/dependency_assumption_diagram.png)
+![dependency assumptions diagram](../_static/images/dependency_assumption_diagram.png)
 
 Array libraries may know how to interoperate with each other, for example by
 constructing their own array type from that of another library or by shared

spec/2021.12/conf.py

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

spec/2021.12/purpose_and_scope.md

@@ -111,7 +111,7 @@ Furthermore, meta-topics included in this standard include:
 The concrete set of functionality that is in scope for this version of the
 standard is shown in this diagram:
 
-![Scope of array API](_static/images/scope_of_array_API.png)
+![Scope of array API](../_static/images/scope_of_array_API.png)
 
 
 **Goals** for the API standard include:

spec/2022.12/assumptions.md

@@ -0,0 +1,77 @@
+(Assumptions)=
+
+# Assumptions
+
+## Hardware and software environments
+
+No assumptions on a specific hardware environment are made. It must be possible
+to create an array library adhering to this standard that runs (efficiently) on
+a variety of different hardware: CPUs with different architectures, GPUs,
+distributed systems and TPUs and other emerging accelerators.
+
+The same applies to software environments: it must be possible to create an
+array library adhering to this standard that runs efficiently independent of
+what compilers, build-time or run-time execution environment, or distribution
+and install method is employed. Parallel execution, JIT compilation, and
+delayed (lazy) evaluation must all be possible.
+
+The variety of hardware and software environments puts _constraints_ on choices
+made in the API standard. For example, JIT compilers may require output dtypes
+of functions to be predictable from input dtypes only rather than input values.
+
+
+(assumptions-dependencies)=
+
+## Dependencies
+
+The only dependency that's assumed in this standard is that on Python itself.
+Python >= 3.8 is assumed, motivated by the use of positional-only parameters
+(see [function and method signatures](API_specification/function_and_method_signatures.md)).
+
+Importantly, array libraries are not assumed to be aware of each other, or of
+a common array-specific layer. The [use cases](use_cases.md) do not require
+such a dependency, and building and evolving an array library is easier without
+such a coupling. Facilitation support of multiple array types in downstream
+libraries is an important use case however, the assumed dependency structure
+for that is:
+
+![dependency assumptions diagram](_static/images/dependency_assumption_diagram.png)
+
+Array libraries may know how to interoperate with each other, for example by
+constructing their own array type from that of another library or by shared
+memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)).
+This can be done without a dependency though - only adherence to a protocol is
+enough.
+
+Array-consuming libraries will have to depend on one or more array libraries.
+That could be a "soft dependency" though, meaning retrieving an array library
+namespace from array instances that are passed in, but not explicitly doing
+`import arraylib_name`.
+
+
+## Backwards compatibility
+
+The assumption made during creation of this standard is that libraries are
+constrained by backwards compatibility guarantees to their users, and are
+likely unwilling to make significant backwards-incompatible changes for the
+purpose of conforming to this standard. Therefore it is assumed that the
+standard will be made available in a new namespace within each library, or the
+library will provide a way to retrieve a module or module-like object that
+adheres to this standard. See {ref}`how-to-adopt-this-api` for more details.
+
+
+## Production code & interactive use
+
+It is assumed that the primary use case is writing production code, for example
+in array-consuming libraries. As a consequence, making it easy to ensure that
+code is written as intended and has unambiguous semantics is preferred - and
+clear exceptions must be raised otherwise.
+
+It is also assumed that this does not significantly detract from the
+interactive user experience. However, in case existing libraries differ in
+behavior, the more strict version of that behavior is typically preferred. A
+good example is array inputs to functions - while NumPy accepts lists, tuples,
+generators, and anything else that could be turned into an array, most other
+libraries only accept their own array types. This standard follows the latter choice.
+It is likely always possible to put a thin "interactive use convenience layer"
+on top of a more strict behavior.

spec/2022.12/benchmark_suite.md

@@ -0,0 +1,3 @@
+# Benchmark suite
+
+Adding a benchmark suite is planned in the future.

spec/2022.12/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/2022.12/future_API_evolution.md

@@ -0,0 +1,60 @@
+(future-API-evolution)=
+
+# Future API standard evolution
+
+## Scope extensions
+
+Proposals for scope extensions in a future version of the API standard will follow
+the process documented at https://github.com/data-apis/governance/blob/master/process_document.md
+
+In summary, proposed new APIs go through several maturity stages, and will only be
+accepted in a future version of this API standard once they have reached the "Final"
+maturity stage, which means multiple array libraries have compliant implementations
+and real-world experience from use of those implementations is available.
+
+
+## Backwards compatibility
+
+Functions, objects, keywords and specified behavior are added to this API standard
+only if those are already present in multiple existing array libraries, and if there is
+data that those APIs are used. Therefore it is highly unlikely that future versions
+of this standard will make backwards-incompatible changes.
+
+The aim is for future versions to be 100% backwards compatible with older versions.
+Any exceptions must have strong rationales and be clearly documented in the updated
+API specification.
+
+
+(api-versioning)=
+
+## Versioning
+
+This API standard uses the following versioning scheme:
+
+- The version is date-based, in the form `yyyy.mm` (e.g., `2020.12`).
+- The version shall not include a standard way to do `alpha`/`beta`/`rc` or
+  `.post`/`.dev` type versions.
+  _Rationale: that's for Python packages, not for a standard._
+- The version must be made available at runtime via an attribute
+  `__array_api_version__` by a compliant implementation, in `'yyyy.mm'` format
+  as a string, in the namespace that implements the API standard.
+  _Rationale: dunder version strings are the standard way of doing this._
+
+No utilities for dealing with version comparisons need to be provided; given
+the format simple string comparisons with Python operators (`=-`, `<`, `>=`,
+etc.) will be enough.
+
+```{note}
+
+Rationale for the `yyyy.mm` versioning scheme choice:
+the API will be provided as part of a library, which already has a versioning
+scheme (typically PEP 440 compliant and in the form `major.minor.bugfix`),
+and a way to access it via `module.__version__`. The API standard version is
+completely independent from the package version. Given the standardization
+process, it resembles a C/C++ versioning scheme (e.g. `C99`, `C++14`) more
+than Python package versioning.
+```
+
+The frequency of releasing a new version of an API standard will likely be at
+regular intervals and on the order of one year, however no assumption on
+frequency of new versions appearing must be made.