docs: Rework XML-RPC docs

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@that.guru>

1 files changed, 31 insertions, 30 deletions

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