docs: Split API docs into their own section

Third time lucky. There are two changes:

- Add a new 'clients' section to the usage doc, allowing us to remove a
  lot of the API nitty gritty stuff from the users guide. This makes
  more sense as users don't really care what API method they're using -
  only what application).

- Change the API docs from the developers guide into a quick start
  section, allowing us to greatly expand the REST API docs to include
  information on pagination, authentication, etc.

Signed-off-by: Stephen Finucane <stephen@that.guru>

3 files changed, 10 insertions, 120 deletions

diff --git a/docs/development/api.rst b/docs/development/api.rst
new file mode 100644
index 0000000..3cfefdb
--- /dev/null
+++ b/docs/development/api.rst
@@ -0,0 +1,10 @@
+Using the APIs
+==============
+
+Patchwork provides two APIs: the legacy :doc:`XML-RPC API <../api/xmlrpc>` and
+the :doc:`REST API <../api/rest>`. You can use these APIs to interact with
+Patchwork programmatically and to develop your own clients.
+
+For quick usage examples of the APIs, refer to the :ref:`documentation
+<api-docs>`. For examples of existing clients, refer to
+:doc:`../usage/clients`.
diff --git a/docs/development/rest.rst b/docs/development/rest.rst
deleted file mode 100644
index efab9f4..0000000
--- a/docs/development/rest.rst
+++ /dev/null
@@ -1,67 +0,0 @@
-The REST API
-============
-
-Patchwork provides a REST API. This API can be used to retrieve and modify
-information about patches, projects and more.
-
-This guide covers development information for the Patchwork REST API. For
-information on using the REST API, refer to `rest`. For information on general
-usage of the REST API, refer to :doc:`../usage/rest`.
-
-.. versionadded:: 2.0
-
-   The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork
-   versions should instead refer to :doc:`xmlrpc`.
-
-Documentation
--------------
-
-Patchwork provides automatically generated documentation for the REST API.
-You can find this at the following URL:
-
-    http://patchwork.example.com/api/
-
-where `patchwork.example.com` refers to the URL of your Patchwork instance.
-
-Interacting with the API
-------------------------
-
-REST APIs run over plain HTTP(S), thus, the API can be interfaced using
-applications or libraries that support this widespread protocol. One such
-application is `curl`__, which can be used to both retrieve and send
-information to the REST API. For example, to get the version of the REST API
-for a Patchwork instance hosted at `patchwork.example.com`, run:
-
-.. code-block:: shell
-
-    $ curl -s http://localhost:8000/api/1.0/ | python -m json.tool
-    {
-        "patches": "http://localhost:8000/api/1.0/patches/",
-        "people": "http://localhost:8000/api/1.0/people/",
-        "projects": "http://localhost:8000/api/1.0/projects/",
-        "users": "http://localhost:8000/api/1.0/users/"
-    }
-
-In addition, a huge variety of libraries are available for interacting with and
-parsing the output of REST APIs. The `requests`__ library is wide-spread and
-well-supported. To repeat the above example using `requests`:
-
-.. code-block:: pycon
-
-    $ python
-    >>> import json
-    >>> import requests
-    >>> r = requests.get('http://patchwork.example.com/api/1.0/')
-    >>> print(json.dumps(r.json(), indent=2))
-    {
-          "users": "http://localhost:8000/api/1.0/users/",
-          "patches": "http://localhost:8000/api/1.0/patches/",
-          "projects": "http://localhost:8000/api/1.0/projects/",
-          "people": "http://localhost:8000/api/1.0/people/"
-    }
-
-Tools like `curl` and libraries like `requests` can be used to build anything
-from small utilities to full-fledged clients targeting the REST API.
-
-__ https://curl.haxx.se/
-__ http://docs.python-requests.org/en/master/
diff --git a/docs/development/xmlrpc.rst b/docs/development/xmlrpc.rst
deleted file mode 100644
index 4b2651f..0000000
--- a/docs/development/xmlrpc.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-The XML-RPC API
-===============
-
-Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
-and modify information about patches, projects and more.
-
-This guide covers development information for the Patchwork XML-RPC API. For
-information on using the REST API, refer to `rest`. For information on general
-usage of the XML-RPC API, refer to :doc:`../usage/xmlrpc`.
-
-Documentation
--------------
-
-Patchwork provides automatically generated documentation for the XML-RPC API.
-You can find this at the following URL:
-
-    http://patchwork.example.com/xmlrpc/
-
-where `patchwork.example.com` refers to the URL of your Patchwork instance.
-
-.. versionchanged:: 1.1
-
-   Automatic documentation generation for the Patchwork API was introduced in
-   Patchwork v1.1. Prior versions of Patchwork do not offer this functionality.
-
-Interacting with the API
-------------------------
-
-The Patchwork XML-RPC API provides a number of "methods". Some methods require
-authentication (via HTTP Basic Auth) while others do not. Authentication uses
-your Patchwork account and the on-server documentation will indicate where it
-is necessary. We will only cover the unauthenticated method here for brevity -
-consult the `xmlrpclib`__ documentation for more detailed examples:
-
-To interact with the Patchwork XML-RPC API, a XML-RPC library should be used.
-Python provides such a library - `xmlrpclib` - in its standard library. For
-example, to get the version of the XML-RPC API for a Patchwork instance hosted
-at `patchwork.example.com`, run:
-
-.. code-block:: pycon
-
-    $ python
-    >>> import xmlrpclib  # or 'xmlrpc.client' for Python 3
-    >>> rpc = xmlrpclib.ServerProxy('http://patchwork.example.com/xmlrpc/')
-    >>> rpc.pw_rpc_version()
-    1.1
-
-Once connected, the `rpc` object will be populated with a list of available
-functions (or procedures, in RPC terminology). In the above example, we used
-the `pw_rpc_version` method, however, it should be possible to use all the
-methods listed in the server documentation.
-
-__ https://docs.python.org/2/library/xmlrpclib.html