Describe what extensions are and how to use them

spec/extensions/index.rst

@@ -3,8 +3,29 @@
 Extensions
 ==========
 
+Extensions are coherent sets of functionality that are commonly implemented
+across array libraries. Each array library supporting this standard may, but is
+not required to, implement an extension. If an extension is supported, it
+must be accessible inside the main array API supporting namespace as a separate
+namespace.
+
+Extension module implementors must aim to provide all functions and other
+public objects in an extension. The rationale for this is that downstream usage
+can then check whether or not the extension is present (using ``hasattr(xp,
+'extension_name')`` should be enough), and can then assume that functions are
+implemented. This in turn makes it also easy for array-consuming libraries to
+document which array libraries they support - e.g., "all libraries implementing
+the array API standard and its linear algebra extension".
+
+The mechanism through which the extension namespace is made available is up to
+the implementer, e.g. via a regular submodule that is imported under the
+``linalg`` name, or via a module-level ``__getattr__``.
+
+
+Extensions
+----------
+
 .. toctree::
-   :caption: Extensions
-   :maxdepth: 3
+   :maxdepth: 1
 
    linear_algebra_functions

spec/extensions/linear_algebra_functions.rst

@@ -5,6 +5,23 @@ Linear Algebra Extension
 
     Array API specification for linear algebra functions.
 
+Extension name and usage
+------------------------
+
+The name of the namespace providing the extension must be: ``linalg``.
+
+If implemented, this ``linalg`` extension must be retrievable via::
+
+    >>> xp = x.__array_namespace__()
+    >>> if hasattr(xp, 'linalg'):
+    >>>    # Use `xp.linalg`
+
+
+General syntax and semantics rules
+----------------------------------
+
+.. TODO: get rid of this here, it's duplicated over and over
+
 A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
 
 -   Positional parameters must be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.