extend docs

docs/source/conf.py

@@ -34,6 +34,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.ifconfig',
+    'sphinx.ext.autosummary',
     'sphinxcontrib.napoleon',
 ]
 

docs/source/pyotrs.rst

 pyotrs
 ======
 
+:mod:`pyotrs`
+-------------
+
+.. automodule:: pyotrs
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 :mod:`pyotrs.client` Module
 ---------------------------
 
 .. automodule:: pyotrs.client
     :members:
+    :private-members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 

pyotrs/client.py

 # -*- coding: utf-8 -*-
-"""Python wrapper for OTRS (using REST API)
-Name:         pyotrs.py
-Description:  PyOTRS
+"""
+
+.. module:: pyotrs.client
+   :platform: Unix
+   :synopsis: Python wrapper for OTRS (using REST API)
+
+.. moduleauthor:: Robert Habermann <robert.habermann@dlh.de>
+
+.. autosummary::
+
+.. note::
+
+   Roughly implements: https://otrs.github.io/doc/api/otrs/5.0/Perl/index.html
 
-Author:       robert.habermann@dlh.de
-Date:         2015-07-20
+This should work too::
 
+   from pyotrs import Client
+   client = Client("https://otrs.example.com", "GenericTicketConnectorREST", "root@localhost", "x")
+   client.session_restore_or_set_up_new()
+   client.ticket_get_by_id(1)
 
-https://otrs.github.io/doc/api/otrs/5.0/Perl/index.html
 
-```
-Kernel::GenericInterface::Operation	GenericInterface Operation interface
+.. note::
 
-Kernel::GenericInterface::Operation
-::Common	                Base class for all Operations
-::Session::Common	        Base class for Session Operations
-::Session::SessionCreate	GenericInterface Session Create Operation backend
-::Test::Test	            GenericInterface Operation Test backend
-::Ticket::Common	        Base class for all Ticket Operations
-::Ticket::TicketCreate	    GenericInterface Ticket TicketCreate Operation backend
-::Ticket::TicketGet	        GenericInterface Ticket Get Operation backend
-::Ticket::TicketSearch	    GenericInterface Ticket Search Operation backend
-::Ticket::TicketUpdate	    GenericInterface Ticket TicketUpdate Operation backend
-```
+   foo bar
+
+   Kernel::GenericInterface::Operation	GenericInterface Operation interface
+   Kernel::GenericInterface::Operation
+   ::Common	                Base class for all Operations
+   ::Session::Common	        Base class for Session Operations
+   ::Session::SessionCreate	GenericInterface Session Create Operation backend
+   ::Test::Test	            GenericInterface Operation Test backend
+   ::Ticket::Common	        Base class for all Ticket Operations
+   ::Ticket::TicketCreate	    GenericInterface Ticket TicketCreate Operation backend
+   ::Ticket::TicketGet	        GenericInterface Ticket Get Operation backend
+   ::Ticket::TicketSearch	    GenericInterface Ticket Search Operation backend
+   ::Ticket::TicketUpdate	    GenericInterface Ticket TicketUpdate Operation backend
 
 """
 
@@ -110,7 +123,19 @@ class OTRSHTTPError(PyOTRSError):
 
 
 class Client(object):
-    """PyOTRS Client class - includes Session handling"""
+    """PyOTRS Client class - includes Session handling
+
+    Args:
+        baseurl (str): Base URL for OTRS System, no trailing slash e.g. http://otrs.example.com
+        webservicename (str): OTRS REST Web Service Name
+        username (str): Username
+        password (str): Password
+        session_id (str): Session ID
+        session_id_file (str): Session ID full path on disk, used to persistently store Session ID
+        session_timeout (int): Session Timeout configured in OTRS (usually 28800 seconds = 8h)
+        https_verify (bool): Should HTTPS certificates be verified (defaults to True)
+
+    """
 
     def __init__(self,
                  baseurl,
@@ -168,12 +193,12 @@ class Client(object):
     def session_valid(self):
         """ check whether Session ID (self.session_id) is currently valid
 
-        Returns:
-            bool: True if valid, False otherwise.
-
         Raises:
             SessionError is self.session_id is not set
 
+        Returns:
+            bool: True if valid, False otherwise.
+
         """
 
         if not self.session_id:
@@ -191,6 +216,9 @@ class Client(object):
     def session_create(self):
         """ create new OTRS Session and store Session ID
 
+        Returns:
+            bool: True if successful, False otherwise.
+
         """
 
         url = "{0.baseurl}/otrs/nph-genericinterface.pl/Webservice/" \
@@ -225,6 +253,10 @@ class Client(object):
         Raises:
             SessionCreateError
             SessionIDFileError
+
+        Returns:
+            bool: True if successful, False otherwise.
+
         """
 
         # try to read session_id from file
@@ -253,6 +285,9 @@ class Client(object):
     def _read_session_id_from_file(self):
         """ Retrieve a stored Session ID from file
 
+        Returns:
+            bool: True if successful, False otherwise.
+
         """
         if os.path.isfile(self.session_id_file):
             with open(self.session_id_file, "r") as f:
@@ -277,8 +312,11 @@ class Client(object):
     def _write_session_id_to_file(self):
         """ Write and store a Session ID to file (rw for user only)
 
-        Todo:
-            Error Handling and return True/False
+        Notes:
+            Todo: Error Handling and return True/False
+
+        Returns:
+            bool: True if successful, False otherwise.
 
         """
         with os.fdopen(os.open(self.session_id_file, os.O_WRONLY | os.O_CREAT, 0o600), 'w') as f:
@@ -289,7 +327,14 @@ class Client(object):
     def _remove_session_id_file(self):
         """ remove session id file (e.g. when it only contains an invalid session id
 
-        Todo:
+        Notes:
+            Todo: Implement this?!
+
+        Raises:
+            NotImplementedError
+
+        Returns:
+            bool: True if successful, False otherwise.
 
         """
         raise NotImplementedError("Not yet done")
@@ -415,13 +460,14 @@ class Client(object):
     def _parse_response_dynamic_fields(self):
         """ Parses dynamic field from response and stores dict in self.ticket_dynamic_fields
 
-        Returns:
-            True
-
         Raises:
             TicketDynamicFieldsNoRequestedError
             TicketDynamicFieldsParseError
 
+        Returns:
+            bool: True if valid, False otherwise.
+
+
         """
 
         if not self.ticket_dynamic_fields_requested:
@@ -450,15 +496,15 @@ class Client(object):
         """Wrapper for search ticket
 
         Args:
-            **kwargs
-
-        Returns:
-            list: tickets that were found
+            **kwargs: Key, Value pairs for Dynamic Field search
 
         Notes:
             If value of kwargs is a datetime object then this object will be
             converted to the appropriate string format for REST API.
 
+        Returns:
+            list: tickets that were found
+
         """
 
         url = "{0.baseurl}/otrs/nph-genericinterface.pl/Webservice/" \
@@ -487,7 +533,7 @@ class Client(object):
         """Wrapper for search ticket for full text search
 
         Args:
-            pattern (str)
+            pattern (str): Search pattern (a % will be added to from and end automatically)
 
         Returns:
             list: tickets that were found
@@ -699,10 +745,10 @@ class Client(object):
         """ datetime_to_pending_time_str
 
         Args:
-            datetime_obj:
+            datetime_obj (datetime):
 
         Returns:
-            str: representing the pending time string format for OTRS REST interface
+            str: The pending time in the format required for OTRS REST interface
 
         """
         pending_time_str = {