[PATCH 2/5] docs: Rework XML-RPC docs

[Stephen Finucane]

Add a barebones usage guide for pwclient and simplify the existing doc
for this API. This entails move the existing doc from the deployment
section to development section, which makes more sense given its focus.

Signed-off-by: Stephen Finucane <stephen at that.guru>
---
 docs/development/xmlrpc.md | 61 +++++++++++++++++++++++-----------------------
 docs/usage/xmlrpc.md       | 37 ++++++++++++++++++++++++++++
 mkdocs.yml                 |  2 ++
 3 files changed, 70 insertions(+), 30 deletions(-)
 create mode 100644 docs/usage/xmlrpc.md

diff --git a/docs/development/xmlrpc.md b/docs/development/xmlrpc.md
index cfa5acf..141dec9 100644
--- a/docs/development/xmlrpc.md
+++ b/docs/development/xmlrpc.md
@@ -1,5 +1,9 @@
 # The XML-RPC API
 
+**NOTE:** This guide covers development information for the Patchwork XML-RPC
+API. For general usage of the API, refer to the [usage
+documentation][doc-usage].
+
 Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
 and modify information about patches, projects and more.
 
@@ -19,33 +23,30 @@ Where `patchwork.example.com` refers to the URL of your Patchwork instance.
 introduced in Patchwork v1.1. Prior versions of Patchwork do not offer this
 functionality.
 
-## Developing Your Own Client
-
-You need to connect to the server. 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 - please
-consult the [`xmlrpclib`] documentation for more detailed examples:
-
-    from __future__ import print_function
-    import sys
-    import xmlrpclib
-
-    url = 'http://patchwork.example.org/xmlrpc/'
-
-    try:
-        rpc = xmlrpclib.ServerProxy(url)
-    except:
-        print('Unable to connect to %s\n' % url, file=sys.stderr)
-        sys.exit(1)
-
-After connecting, the `rpc` object will be populated with a list of available
-functions (or procedures, in RPC terminology). For example, if we continue
-with the above example:
-
-    print(rpc.pw_rpc_version())
-
-It should be possible to use all the methods listed in the
-[server's documentation](#patchwork-api-documentation).
-
-[`xmlrpclib`]: https://docs.python.org/2/library/xmlrpclib.html
+## Interacting with the API
+
+**NOTE:** 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 - please consult the [`xmlrpclib`][ref-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`][ref-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:
+
+    $ 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](#patchwork-api-documentation).
+
+[doc-usage]: ../usage/xmlrpc.md
+[ref-xmlrpclib]: https://docs.python.org/2/library/xmlrpclib.html
diff --git a/docs/usage/xmlrpc.md b/docs/usage/xmlrpc.md
new file mode 100644
index 0000000..de95a07
--- /dev/null
+++ b/docs/usage/xmlrpc.md
@@ -0,0 +1,37 @@
+# The XML-RPC API
+
+**NOTE:** This guide covers usage information for the Patchwork XML-RPC API.
+For information on developing custom applications or clients for this API,
+refer to the [developers documentation][doc-development].
+
+Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
+and modify information about patches, projects and more.
+
+**NOTE:** The XML-RPC API can be enabled/disabled by the administrator: it may
+not be available in every instance.
+
+## 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][ref-pw-oz], 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:
+
+    $ pwclient --help
+
+[doc-development]: ../development/xmlrpc.md
diff --git a/mkdocs.yml b/mkdocs.yml
index 0bbe7e1..5980ac9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,3 +14,5 @@ pages:
  - Deployment Guide:
    - Installation: 'deployment/installation.md'
    - Upgrading: 'deployment/upgrading.md'
+ - Usage Guide:
+   - XML-RPC API: 'usage/xmlrpc.md'
-- 
2.7.4