Describe what extensions are and how to use themo (#470)

Note that an alternative idea discussed earlier was a separate function
`get_extension()`, but IIRC that was not considered a good idea.
Now that we have module-level `__getattr__`'s, it should not be
a problem for any library to use a specified name like `linalg` or
`fft`.

Whether the functions in the `linalg` extensions should all be required
to exist or not was discussed in gh-403 (no clear conclusion there).
One option discussed there to deal with hard to implement or more niche
APIs is to create a separate status/label or some other way to track
desired signatures (details to be worked out if we want to go that way).

Author: rgommers

spec/extensions/index.rst

@@ -3,9 +3,30 @@
 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
 
    fourier_transform_functions
    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.