Restructure docstrings for better html output.

Change-Id: Ic935e8f85e2ad333677770746c15648ae5bac339

4 files changed, 161 insertions, 88 deletions

diff --git a/pygerrit/__init__.py b/pygerrit/__init__.py
index d9ce98d..416600a 100644
--- a/pygerrit/__init__.py
+++ b/pygerrit/__init__.py
@@ -26,8 +26,11 @@
 def from_json(json_data, key):
     """ Helper method to extract values from JSON data.
 
-    Return the value of `key` from `json_data`, or None if `json_data`
-    does not contain `key`.
+    :arg dict json_data: The JSON data
+    :arg str key: Key to get data for.
+
+    :Returns: The value of `key` from `json_data`, or None if `json_data`
+        does not contain `key`.
 
     """
     if key in json_data:
@@ -38,9 +41,11 @@ def from_json(json_data, key):
 def escape_string(string):
     """ Escape a string for use in Gerrit commands.
 
-    Return the string with necessary escapes and surrounding double quotes
-    so that it can be passed to any of the Gerrit commands that require
-    double-quoted strings.
+    :arg str string: The string to escape.
+
+    :returns: The string with necessary escapes and surrounding double quotes
+        so that it can be passed to any of the Gerrit commands that require
+        double-quoted strings.
 
     """
 
@@ -52,17 +57,16 @@ def escape_string(string):
 
 class GerritReviewMessageFormatter(object):
 
-    """ Helper class to format review messages that are sent to Gerrit. """
+    """ Helper class to format review messages that are sent to Gerrit.
 
-    def __init__(self, header=None, footer=None):
-        """ Constructor.
+    :arg str header: (optional) If specified, will be prepended as the first
+        paragraph of the output message.
+    :arg str footer: (optional) If specified, will be appended as the last
+        paragraph of the output message.
 
-        If `header` is specified, it will be prepended as the first
-        paragraph of the output message.  If `footer` is specified it
-        will be appended as the last paragraph of the output message.
-
-        """
+    """
 
+    def __init__(self, header=None, footer=None):
         self.paragraphs = []
         if header:
             self.header = header.strip()
@@ -76,11 +80,11 @@ class GerritReviewMessageFormatter(object):
     def append(self, data):
         """ Append the given `data` to the output.
 
-        If `data` is a list, it is formatted as a bullet list with each
-        entry in the list being a separate bullet.  Otherwise if it is a
-        string, the string is added as a paragraph.
+        :arg data: If a list, it is formatted as a bullet list with each
+            entry in the list being a separate bullet.  Otherwise if it is a
+            string, the string is added as a paragraph.
 
-        Raises ValueError if `data` is not a list or a string.
+        :raises: ValueError if `data` is not a list or a string.
 
         """
         if not data:
@@ -114,15 +118,19 @@ class GerritReviewMessageFormatter(object):
             raise ValueError('Data must be a list or a string')
 
     def is_empty(self):
-        """ Return True if no paragraphs have been added. """
+        """ Check if the formatter is empty.
+
+        :Returns: True if empty, i.e. no paragraphs have been added.
+
+        """
         return not self.paragraphs
 
     def format(self):
         """ Format the message parts to a string.
 
-        Return a string of all the message parts separated into paragraphs,
-        with header and footer paragraphs if they were specified in the
-        constructor.
+        :Returns: A string of all the message parts separated into paragraphs,
+            with header and footer paragraphs if they were specified in the
+            constructor.
 
         """
         message = ""
diff --git a/pygerrit/client.py b/pygerrit/client.py
index 4095914..73f43be 100644
--- a/pygerrit/client.py
+++ b/pygerrit/client.py
@@ -35,7 +35,13 @@ from .stream import GerritStream
 
 class GerritClient(object):
 
-    """ Gerrit client interface. """
+    """ Gerrit client interface.
+
+    :arg str host: The hostname.
+    :arg str username: (optional) The username to use when connecting.
+    :arg str port: (optional) The port number to connect to.
+
+    """
 
     def __init__(self, host, username=None, port=None):
         self._factory = GerritEventFactory()
@@ -44,25 +50,45 @@ class GerritClient(object):
         self._ssh_client = GerritSSHClient(host, username=username, port=port)
 
     def gerrit_version(self):
-        """ Return the version of Gerrit that is connected to. """
+        """ Get the Gerrit version.
+
+        :Returns: The version of Gerrit that is connected to, as a string.
+
+        """
         return self._ssh_client.get_remote_version()
 
     def gerrit_info(self):
-        """ Return the username, and version of Gerrit that is connected to. """
+        """ Get connection information.
+
+        :Returns: A tuple of the username, and version of Gerrit that is
+            connected to.
+
+        """
+
         return self._ssh_client.get_remote_info()
 
     def run_command(self, command):
-        """ Run the command.  Return the result. """
+        """ Run a command.
+
+        :arg str command: The command to run.
+
+        :Return: The result as a string.
+
+        :Raises: `ValueError` if `command` is not a string.
+
+        """
         if not isinstance(command, basestring):
             raise ValueError("command must be a string")
         return self._ssh_client.run_gerrit_command(command)
 
     def query(self, term):
-        """ Run `gerrit query` with the given `term`.
+        """ Run a query.
+
+        :arg str term: The query term to run.
 
-        Return a list of results as `Change` objects.
+        :Returns: A list of results as :class:`pygerrit.models.Change` objects.
 
-        Raise `ValueError` if `term` is not a string.
+        :Raises: `ValueError` if `term` is not a string.
 
         """
         results = []
@@ -111,10 +137,14 @@ class GerritClient(object):
     def get_event(self, block=True, timeout=None):
         """ Get the next event from the queue.
 
-        Return a `GerritEvent` instance, or None if:
-         - `block` is False and there is no event available in the queue, or
-         - `block` is True and no event is available within the time
-           specified by `timeout`.
+        :arg boolean block: Set to True to block if no event is available.
+        :arg seconds timeout: Timeout to wait if no event is available.
+
+        :Returns: The next event as a :class:`pygerrit.events.GerritEvent`
+            instance, or `None` if:
+             - `block` is False and there is no event available in the queue, or
+             - `block` is True and no event is available within the time
+               specified by `timeout`.
 
         """
         try:
@@ -125,8 +155,10 @@ class GerritClient(object):
     def put_event(self, data):
         """ Create event from `data` and add it to the queue.
 
-        Raise GerritError if the queue is full, or the factory could not
-        create the event.
+        :arg json data: The JSON data from which to create the event.
+
+        :Raises: :class:`pygerrit.error.GerritError` if the queue is full, or
+            the factory could not create the event.
 
         """
         try:
diff --git a/pygerrit/rest/__init__.py b/pygerrit/rest/__init__.py
index c5d0ea1..3cbff2b 100644
--- a/pygerrit/rest/__init__.py
+++ b/pygerrit/rest/__init__.py
@@ -31,13 +31,14 @@ GERRIT_AUTH_SUFFIX = "/a"
 
 
 def _decode_response(response):
-    """ Decode the `response` received from a REST API call.
+    """ Strip off Gerrit's magic prefix and decode a response.
 
-    Strip off Gerrit's magic prefix if it is there, and return decoded
-    JSON content or raw text if it cannot be decoded as JSON.
+    :returns:
+        Decoded JSON content as a dict, or raw text if content could not be
+        decoded as JSON.
 
-    Raise requests.HTTPError if the response contains an HTTP error status
-    code.
+    :raises:
+        requests.HTTPError if the response contains an HTTP error status code.
 
     """
     response.raise_for_status()
@@ -52,22 +53,19 @@ def _decode_response(response):
 
 class GerritRestAPI(object):
 
-    """ Interface to the Gerrit REST API. """
+    """ Interface to the Gerrit REST API.
 
-    def __init__(self, url, auth=None, verify=True):
-        """ Constructor.
-
-        `url` is assumed to be the full URL to the server, including the
-        'http(s)://' prefix.
-
-        If `auth` is specified, it must be a derivation of the `AuthBase`
-        class from the `requests` module.  The `url` will be adjusted if
-        necessary to make sure it includes Gerrit's authentication suffix.
+    :arg str url: The full URL to the server, including the `http(s)://` prefix.
+        If `auth` is given, `url` will be automatically adjusted to include
+        Gerrit's authentication suffix.
+    :arg auth: (optional) Authentication handler.  Must be derived from
+        `requests.auth.AuthBase`.
+    :arg boolean verify: (optional) Set to False to disable verification of
+        SSL certificates.
 
-        If `verify` is False, the underlying requests library will be
-        configured to not attempt to verify SSL certificates.
+    """
 
-        """
+    def __init__(self, url, auth=None, verify=True):
         headers = {'Accept': 'application/json',
                    'Accept-Encoding': 'gzip'}
         self.kwargs = {'auth': auth,
@@ -92,23 +90,30 @@ class GerritRestAPI(object):
         logging.debug("url %s", self.url)
 
     def make_url(self, endpoint):
-        """ Make the necessary url from `endpoint`.
+        """ Make the full url for the endpoint.
 
-        Strip leading slashes off the endpoint, and return the full
-        url.
+        :arg str endpoint: The endpoint.
 
-        Raise requests.RequestException on timeout or connection error.
+        :returns:
+            The full url with leading slashes stripped.
+
+        :raises:
+            requests.RequestException on timeout or connection error.
 
         """
         endpoint = endpoint.lstrip('/')
         return self.url + endpoint
 
     def get(self, endpoint, **kwargs):
-        """ Send HTTP GET to `endpoint`.
+        """ Send HTTP GET to the endpoint.
+
+        :arg str endpoint: The endpoint to send to.
 
-        Return JSON decoded result.
+        :returns:
+            JSON decoded result.
 
-        Raise requests.RequestException on timeout or connection error.
+        :raises:
+            requests.RequestException on timeout or connection error.
 
         """
         kwargs.update(self.kwargs.copy())
@@ -116,11 +121,15 @@ class GerritRestAPI(object):
         return _decode_response(response)
 
     def put(self, endpoint, **kwargs):
-        """ Send HTTP PUT to `endpoint`.
+        """ Send HTTP PUT to the endpoint.
+
+        :arg str endpoint: The endpoint to send to.
 
-        Return JSON decoded result.
+        :returns:
+            JSON decoded result.
 
-        Raise requests.RequestException on timeout or connection error.
+        :raises:
+            requests.RequestException on timeout or connection error.
 
         """
         kwargs.update(self.kwargs.copy())
@@ -130,11 +139,15 @@ class GerritRestAPI(object):
         return _decode_response(response)
 
     def post(self, endpoint, **kwargs):
-        """ Send HTTP POST to `endpoint`.
+        """ Send HTTP POST to the endpoint.
 
-        Return JSON decoded result.
+        :arg str endpoint: The endpoint to send to.
 
-        Raise requests.RequestException on timeout or connection error.
+        :returns:
+            JSON decoded result.
+
+        :raises:
+            requests.RequestException on timeout or connection error.
 
         """
         kwargs.update(self.kwargs.copy())
@@ -144,11 +157,15 @@ class GerritRestAPI(object):
         return _decode_response(response)
 
     def delete(self, endpoint, **kwargs):
-        """ Send HTTP DELETE to `endpoint`.
+        """ Send HTTP DELETE to the endpoint.
+
+        :arg str endpoint: The endpoint to send to.
 
-        Return JSON decoded result.
+        :returns:
+            JSON decoded result.
 
-        Raise requests.RequestException on timeout or connection error.
+        :raises:
+            requests.RequestException on timeout or connection error.
 
         """
         kwargs.update(self.kwargs.copy())
@@ -156,11 +173,17 @@ class GerritRestAPI(object):
         return _decode_response(response)
 
     def review(self, change_id, revision, review):
-        """ Send HTTP POST with review parameters.
+        """ Submit a review.
+
+        :arg str change_id: The change ID.
+        :arg str revision: The revision.
+        :arg str review: The review details as a :class:`GerritReview`.
 
-        Return JSON decoded result.
+        :returns:
+            JSON decoded result.
 
-        Raise requests.RequestException on timeout or connection error.
+        :raises:
+            requests.RequestException on timeout or connection error.
 
         """
 
@@ -170,18 +193,15 @@ class GerritRestAPI(object):
 
 class GerritReview(object):
 
-    """Class to handle inline reviews."""
+    """ Encapsulation of a Gerrit review.
 
-    def __init__(self, message=None, labels=None, comments=None):
-        """ Initialization.
+    :arg str message: (optional) Cover message.
+    :arg dict labels: (optional) Review labels.
+    :arg dict comments: (optional) Inline comments.
 
-        Format Eg:
-        labels :
-        {'Verified': 1, 'Code-Review': -1}
-        comments :
-        [{'filename': 'Makefile', 'line': 10, 'message': 'inline message'}]
+    """
 
-        """
+    def __init__(self, message=None, labels=None, comments=None):
         self.message = message if message else ""
         if labels:
             if not isinstance(labels, dict):
@@ -198,22 +218,36 @@ class GerritReview(object):
             self.comments = {}
 
     def set_message(self, message):
-        """Set review message."""
+        """ Set review cover message.
+
+        :arg str message: Cover message.
+
+        """
         self.message = message
 
     def add_labels(self, labels):
-        """Set Labels.
+        """ Add labels.
+
+        :arg dict labels: Labels to add, for example
+
+        Usage::
 
-        Format Eg:  {'Verified': 1, 'Code-Review': -1}
+            add_labels({'Verified': 1,
+                        'Code-Review': -1})
 
         """
         self.labels.update(labels)
 
     def add_comments(self, comments):
-        """Add inline comments.
+        """ Add inline comments.
+
+        :arg dict comments: Comments to add.
+
+        Usage::
 
-        Format Eg:
-        [{'filename': 'Makefile', 'line': 10, 'message': 'inline message'}]
+            add_comments([{'filename': 'Makefile',
+                           'line': 10,
+                           'message': 'inline message'}])
 
         """
         for comment in comments:
@@ -230,7 +264,6 @@ class GerritReview(object):
                     self.comments.update(file_comment)
 
     def __str__(self):
-        """Return review in str format."""
         review_input = {}
         if self.message:
             review_input.update({'message': self.message})
diff --git a/pygerrit/rest/auth.py b/pygerrit/rest/auth.py
index c43c3fa..a7bc08c 100644
--- a/pygerrit/rest/auth.py
+++ b/pygerrit/rest/auth.py
@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-""" Authentication classes. """
+""" Authentication handlers. """
 
 from requests.auth import HTTPDigestAuth, HTTPBasicAuth
 from requests.utils import get_netrc_auth