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, 47 insertions, 89 deletions

diff --git a/docs/usage/clients.rst b/docs/usage/clients.rst
new file mode 100644
index 0000000..a131fc8
--- /dev/null
+++ b/docs/usage/clients.rst
@@ -0,0 +1,47 @@
+Clients
+=======
+
+A number of clients are available for interacting with Patchwork's various
+APIs.
+
+pwclient
+--------
+
+The `pwclient` application, provided with Patchwork, can be used to interact
+with Patchwork from the command line. Functionality provided by `pwclient`
+includes:
+
+- Listing patches, projects, and checks
+- Downloading and applying patches to a local code base
+- Modifying the status of patches
+- Creating new checks
+
+`pwclient` can be downloaded from the `Ozlabs Patchwork instance`__, or at the
+following path for most other Patchwork instances:
+
+    http://patchwork.example.com/pwclient/
+
+where `patchwork.example.com` corresponds to the URL a Patchwork instance is
+hosted at.
+
+Once downloaded, view information about all the operations supported by
+`pwclient`, run:
+
+.. code-block:: shell
+
+    $ pwclient --help
+
+__ https://patchwork.ozlabs.org/pwclient/
+
+git-pw
+------
+
+The `git-pw` application can be used to integrate Git with Patchwork. The
+`git-pw` application relies on the REST API and can be used to interact to
+list, download and apply series, bundles and individual patches.
+
+More information on `git-pw`, including installation and usage instructions,
+can be found in the `documentation`__ and the `GitHub repo`__.
+
+__ https://git-pw.readthedocs.io/
+__ https://github.com/getpatchwork/git-pw
diff --git a/docs/usage/rest.rst b/docs/usage/rest.rst
deleted file mode 100644
index 33808bc..0000000
--- a/docs/usage/rest.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-The REST API
-============
-
-.. note::
-
-   This guide covers usage information for the Patchwork REST API. For
-   information on using the XML-RPC API, refer to :doc:`xmlrpc`. For
-   information on developing custom applications or clients for this API, refer
-   to the :doc:`../development/rest`.
-
-Patchwork provides a REST API. This API can be used to retrieve and modify
-information about patches, projects and more.
-
-.. important::
-
-   The REST API can be enabled/disabled by the administrator: it may not be
-   available in every instance. Refer to ``/about`` on your given instance for
-   the status of the API, e.g.
-
-       https://patchwork.ozlabs.org/about
-
-.. versionadded:: 2.0
-
-   The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork
-   versions should instead refer to :doc:`xmlrpc`.
-
-git-pw
-------
-
-The `git-pw` application can be used to integrate Git with Patchwork. The
-`git-pw` application relies on the REST API and can be used to interact to
-list, download and apply series, bundles and individual patches.
-
-More information on `git-pw`, including installation and usage instructions,
-can be found in the `documentation`__ and the `GitHub repo`__.
-
-__ https://git-pw.readthedocs.io/
-__ https://github.com/getpatchwork/git-pw
diff --git a/docs/usage/xmlrpc.rst b/docs/usage/xmlrpc.rst
deleted file mode 100644
index 1bebcc8..0000000
--- a/docs/usage/xmlrpc.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-The XML-RPC API
-===============
-
-.. note::
-
-   This guide covers usage information for the Patchwork XML-RPC API.  For
-   information on using the REST API, refer to :doc:`rest`. For information on
-   developing custom applications or clients for this API, refer to the
-   :doc:`../development/xmlrpc`.
-
-Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
-and modify information about patches, projects and more.
-
-.. important::
-
-   The XML-RPC API can be enabled/disabled by the administrator: it may not be
-   available in every instance. Refer to ``/about`` on your given instance for
-   the status of the API, e.g.
-
-       https://patchwork.ozlabs.org/about
-
-   This URL is only supported on Patchwork 2.0+.
-
-pwclient
---------
-
-The `pwclient` application, provided with Patchwork, can be used to interact
-with Patchwork from the command line. Functionality provided by `pwclient`
-includes:
-
-* Listing patches, projects, and checks
-* Downloading and applying patches to a local code base
-* Modifying the status of patches
-* Creating new checks
-
-pwclient can be downloaded from the `Ozlabs Patchwork instance`__, or at the
-following path for other Patchwork instances:
-
-    http://patchwork.example.com/pwclient/
-
-where `patchwork.example.com` corresponds to the URL a Patchwork instance is
-hosted at.
-
-Once downloaded, to view information about all the operations supported by
-`pwclient`, run:
-
-.. code-block:: shell
-
-    $ pwclient --help
-
-__ https://patchwork.ozlabs.org/pwclient/