Improve documentation of client class

docs/source/pdc_client.rst

@@ -86,6 +86,33 @@ This is much more user friendly user interface. A single invocation can perform
 multiple requests depending on what subcommand you used.
 
 
+Python API
+----------
+
+When writing a client code interfacing with PDC server, you might find
+``PDCClient`` handy. It provides access to the configuration defined above and
+automates obtaining authorization token.
+
+To use this module, you will need to install its dependencies. These include
+
+ * `requests <http://docs.python-requests.org/en/latest/>`_
+ * `requests-kerberos <https://github.com/requests/requests-kerberos/>`_
+ * `beanbag <http://beanbag.readthedocs.org/en/latest/>`_
+
+.. autoclass:: pdc_client.PDCClient
+
+   .. automethod:: pdc_client.PDCClient.__init__
+
+   .. automethod:: pdc_client.PDCClient.set_comment
+
+When working with paginated responses, there is a utility function to simplify
+that. From client code it is iterating single object. Behind the scenes it will
+download the first page, once all results from that page are exhausted, it will
+get another page until everything is processed.
+
+.. autofunction:: pdc_client.get_paged
+
+
 Known Issues
 ------------
 
@@ -136,5 +163,5 @@ General
 The PDC Client (package name: pdc_client) is mainly build up with Python
 `argparse` module and PDC's Python module `pdc_client`.
 
-It is powered by `Beanbag <https://github.com/dmach/beanbag>`_, a simple module
+It is powered by `BeanBag`_, a simple module
 that lets you access REST APIs in an easy way.

pdc_client/__init__.py

@@ -41,10 +41,19 @@ def read_config_file(server_alias):
 
 def get_paged(res, **kwargs):
     """
-    This call is equivalent to `res(**kwargs)`, only it retrieves all pages and
-    returns the results joined into a single iterable. The advantage over
+    This call is equivalent to ``res(**kwargs)``, only it retrieves all pages
+    and returns the results joined into a single iterable. The advantage over
     retrieving everything at once is that the result can be consumed
     immediately.
+
+    :param res:     what resource to connect to
+    :param kwargs:  filters to be used
+
+    ::
+
+        # Example: Iterate over all active releases
+        for release in get_paged(client['releases']._, active=True):
+            ...
     """
     def worker():
         kwargs['page'] = 1
@@ -59,7 +68,23 @@ def worker():
 
 
 class PDCClient(object):
+    """BeanBag wrapper specialized for PDC access.
+
+    This class wraps general BeanBag.v1 objects, but provides easy-to-use
+    interface that can use configuration files for specifying server
+    connections. The authentication token is automatically retrieved (if
+    needed).
+    """
     def __init__(self, server):
+        """Create new client instance.
+
+        Once the class is instantiated, use it as you would use a regular
+        BeanBag object. Please see its documentation to see how to use this
+        class to perform requests.
+
+        :param server:     server API url or server name from configuration
+        :paramtype server: string
+        """
         if not server:
             raise TypeError('Server must be specified')
         self.session = requests.Session()
@@ -132,4 +157,11 @@ def __getitem__(self, *args, **kwargs):
         return self.client.__getitem__(*args, **kwargs)
 
     def set_comment(self, comment):
+        """Set PDC Change comment to be stored on the server.
+
+        Once you set the comment, it will be sent in all subsequent requests.
+
+        :param comment:     what comment to send to the server
+        :paramtype comment: string
+        """
         self.session.headers["PDC-Change-Comment"] = comment