Adding some documentation

docs/index.rst

@@ -8,9 +8,11 @@ Welcome to Mitel OMMClient2's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
-:ref:`api`
+   manual/client
+   manual/connection
+   manual/messages
+   api/modules
 
 Indices and tables
 ==================

docs/manual/client.rst

@@ -0,0 +1,42 @@
+Client Usage Manual
+===================
+
+This should give you an introduction on how to use :class:`mitel_ommclient2.client.OMMClient2`.
+
+If you are not interested in using the abstraction layer, even though it is recommended,
+have a look at :doc:`/manual/connection` .
+
+Creating a client
+-----------------
+
+To start with this client, you need login credentials for your OMM. The permissions
+you have using this client are the ones assinged to the user you login with.
+
+You are required to specify at least the host to connect to, a username and a corresponding
+password. For further options see :class:`mitel_ommclient2.client.OMMClient2`.
+
+.. code-block:: python
+
+    import mitel_ommclient2
+
+    c = mitel_ommclient2.OMMClient2("omm.local", "admin", "password")
+
+Creating this object will directly connect to the API of the corresponding host.
+Failure in connection or authenticating will raise an excaption.
+
+Using the API
+-------------
+
+:class:`mitel_ommclient2.client.OMMClient2` ships with several mathods that wraps and
+validate common API requests. See class documentation to get and overview and options.
+
+.. code-block:: python
+
+    c.ping()
+
+Making custom requests
+----------------------
+
+:func:`mitel_ommclient2.client.OMMClient2.request` allowes you to send custom requests.
+It just passes arguments and results to :func:`mitel_ommclient2.connection.Connection.request`.
+See :doc:`/manual/connection` about using this.

docs/manual/connection.rst

@@ -0,0 +1,73 @@
+Connection Usage Manual
+=======================
+
+This manual documents the underlying connation infrastructure. If you just wanna
+use the API, please see :doc:`/manual/client` .
+
+Using connections
+-----------------
+
+The :class:`mitel_ommclient2.connection.Connection` requires just host and port
+to establish a transport to the API.
+
+.. code-block:: python
+
+    import mitel_ommclient2
+
+    conn = mitel_ommclient2..connection.Connection("omm.local")
+
+To actually connect to the OMM, you need to call :func:`mitel_ommclient2.connection.Connection.connect`.
+
+.. code-block:: python
+
+    conn.connect()
+
+This establishes a connections and spawns a thread that reads new messages from
+the connection.
+
+Please use :func:`mitel_ommclient2.connection.Connection.close` when finishing
+with talking to the API.
+
+.. code-block:: python
+
+    conn.close()
+
+This stops the thread and closes the connection.
+
+Making requests
+---------------
+
+:func:`mitel_ommclient2.connection.Connection.request` provides a synchronous way
+to work with the asynchronous API of the OMM.
+
+You hand over a Request object and receive a response object.
+
+.. code-block:: python
+
+    >>> request = mitel_ommclient2.messages.Ping()
+    >>> r = conn.request(request)
+    >>> r.name
+    'PingResp'
+
+Request will generate an internal sequence number and attach this to you request
+object. After sending you request to the OMM it will wait for a response with the
+corresponding sequence number. Please note: Even though you can set your own sequence
+number in the request object, it will be overridden by :func:`mitel_ommclient2.connection.Connection.request`.
+The response object will contain the sequence number generated by :func:`mitel_ommclient2.connection.Connection.request`
+and not the one set by your own.
+
+See :doc:`/manual/messages` on how to work with message objects.
+
+Authenticate
+------------
+
+Before you can send general requests, you need to authenticate youself agains the
+OMM. The only allowed message on a new connection is :func:`mitel_ommclient2.messages.Open`.
+
+.. code-block:: python
+
+    >>> r = conn.request(mitel_ommclient2.messages.Open("username", "password"))
+    >>> r.raise_on_error()
+
+If this throws no exception, login is was successful and you can send other requests.
+If your authentication request failed, you can just send a new Open message to try again.

docs/manual/messages.rst

@@ -0,0 +1,53 @@
+Message Usage Manual
+====================
+
+The API consists of three main message types: request, response and event. They
+are represented by :class:`mitel_ommclient2.messages.Request`, :class:`mitel_ommclient2.messages.Response`
+and events aren't supported yet.
+
+There are several subclasses for each messages type, but they are just just overlays
+to provide a conveinient interface to message content using attributes.
+
+Each message provides three attributes that define the central interfaces:
+
+  * name
+  * attrs
+  * childs
+
+Using messages
+--------------
+
+Just choose one of several message classes of :module:`mitel_ommclient2.messages`
+and hand it over to :func:`mitel_ommclient2.client.OMMClient2.request` or
+:func:`mitel_ommclient2.connection.Connection.request`.
+
+.. code-block:: python
+
+    import time
+
+    my_time = int(time.time())
+
+    request = mitel_ommclient2.messages.Ping(timeStamp=my_time)
+    r = c.request(request)
+
+    ping = r.timeStamp - my_time
+
+Crafting your own messages
+--------------------------
+
+It some cases your message class isn't implemented yet. Then you can craft the
+message yourself.
+
+.. code-block:: python
+
+    import time
+
+    my_time = int(time.time())
+
+    request = mitel_ommclient2.messages.Request("Ping")
+    request.attrs = {
+      "timeStamp": my_time,
+    }
+    r = c.request(request)
+
+    ping = r.attrs["timeStamp"] - my_time