Add a description of how to adopt the API (#33)

* Add a description of how to adopt the API

Ref discussion from 20 Aug. The thing I left out of this text
is a global dispatch. The last point made on that was:

    ... there is some inherent difficulties. Local dispatch is the more
    straightforward approach, but difficulties arise when you want a
    particular function to use a particular backend implementation.

and I wasn't quite sure if that concern is valid - maybe I'm missing
some details. If the "you" in there is the library author, then
they should just ignore the whole API standard namespace and just do
`import lib_I_want; lib_I_want.<somefunc>`.
If it is the end user, then they normally would pass in an array of
the right type that would control this. So the one case I see where
the concern applies is if there is some function that does _not_ take
any array input, but creates arrays internally _and_ the default array
type for that creation is somehow undesirable. That seems a bit
unlikely.

* Change the namespace convention to `xp` (borrowed from CuPy)

* Clarify that using an API version to retrieve the namespace is optional

* Minor textual clarification to address review comment.

Author: rgommers

spec/API_specification/index.rst

@@ -1,3 +1,5 @@
+.. _api-specification:
+
 API specification
 =================
 
@@ -17,6 +19,13 @@ API specification
    statistical_functions
    linear_algebra_functions
    searching_functions
+   linear_algebra_functions
    set_functions
    utility_functions
    constants
+
+
+.. _api-versioning:
+
+TODO: add `__array_api_version__` (or similar) version here, and the way to
+      retrieve it - see https://github.com/data-apis/workgroup/issues/24

spec/purpose_and_scope.md

@@ -232,6 +232,53 @@ For guidance on how to read and understand the type annotations included in this
 
 ## How to adopt this API
 
+Most (all) existing array libraries will find something in this API standard
+that is incompatible with a current implementation, and that they cannot
+change due to backwards compatibility concerns. Therefore we expect that each
+of those libraries will want to offer a standard-compliant API in a _new
+namespace_. The question then becomes: how does a user access this namespace?
+
+The simplest method is: document the import to use to directly access the
+namespace (e.g. `import package_name.array_api`). This has two issues though:
+
+1. Array-consuming libraries that want to support multiple array libraries
+   then have to explicitly import each library.
+2. It is difficult to _version_ the array API standard implementation (see
+   :ref:`api-versioning`).
+
+To address both issues, a uniform way must be provided by a conforming
+implementation to access the API namespace, namely a method on the array object:
+
+```
+xp = x.__array_namespace__()
+```
+
+The method must take one keyword, `api_version=None`, to make it possible to
+request a specific API version:
+
+```
+xp = x.__array_namespace__(api_version='2020.10')
+```
+
+.. note::
+
+    This is inspired by [NEP 37](https://numpy.org/neps/nep-0037-array-module.html#how-to-use-get-array-module),
+    however it avoids adding a dependency on NumPy or having to provide a
+    separate package just to do `get_array_module(x)`
+
+    NEP 37 is still in flux (it was just accepted by JAX and TensorFlow on an
+    experimental basis), and it's possible that that should be accepted instead.
+
+    TBD: a decision must be made on this topic before a first version of the
+    standard can become final. We prefer to delay this decision, to see how
+    NEP 37 adoption will work out.
+
+The `xp` namespace must contain the array object and all functionality
+specified in :ref:`api-specification`. It may contain other functionality,
+however it is recommended not to add other functions or objects, because that
+may make it harder for users to write code that will work with multiple array
+libraries.
+
 
 * * *