updated documentation

docs/DevelopersNotes.rst

@@ -0,0 +1,82 @@
+********************************
+Developers Notes for Hangout API
+********************************
+
+Hangout API Architecture Overview
+=================================
+
+Hangout API has modular structure. Base Hangout class provides only
+`few methods`_ to control call. All other functionality are dynamically
+extends base class by using utility from zope.component (part of ZCA
+implementation). It has a bunch of build-in extensions:
+    * Regular Hangout PlugIn's:
+        * :doc:`api/Audio`
+        * :doc:`api/Microphone`
+        * :doc:`api/Video`
+        * :doc:`api/Bandwidth`
+    * OnAir PlugIn's:
+        * :doc:`api/Broadcast`
+        * :doc:`api/Cameraman`
+        * :doc:`api/Toolbox`
+        * :doc:`api/ControlRoom`
+
+.. _few methods: api/Hangouts.html#hangout_api.base.Hangouts
+
+
+Writing Hangouts Extensions
+===========================
+
+You can easily extend Hangout functionality by registering zope.component
+utility (just make sure that this code executes on package initialization):
+
+.. code:: python
+
+    provideUtility(MyNewExtension, IModule, 'my_new_extension')
+
+After you do it your new extension will be accessible from Hangout instance:
+
+.. code:: python
+
+    hangout = Hangouts()
+    hangout.my_new_extension.do_some_thing()
+
+List of available interfaces you can find at hangout_api.interfaces:
+
+.. literalinclude:: ../hangout_api/interfaces.py
+    :language: python
+
+
+For more examples look at hangout_api.setting and hangout_api.gadgets.
+
+As you can see from interfaces your class in initialization step should
+take *base* argument, which is instance of `hangout_api.utils.Utils`_ class.
+
+.. _hangout_api.utils.Utils: api/BaseUtils.html#hangout_api.utils.Utils
+
+PlugIn's development
+=====================
+
+The PlugIn's actually are a case Hangouts Extensions, but here you need to
+handle the browser frames context. To make that easier there is
+**hangout_api.gadgets.utils.gadget_context_handle**:
+
+.. code:: python
+
+    from hangout_api.gadgets.utils import gadget_context_handler
+
+    class Cameraman(object):
+
+        def __init__(self, base):
+            self.base = base
+
+        @gadget_context_handler("Cameraman")
+        def mute_new_guests(self, value=None):
+            pass
+
+For more examples take a look at *hangout_api.gadgets*.
+
+
+Testing
+=======
+
+.. _few methods: api/Hangouts

docs/api/BaseUtils.rst

@@ -0,0 +1,2 @@
+.. automodule:: hangout_api.utils
+    :members:

docs/index.rst

@@ -10,28 +10,16 @@ Hangout API is python API for google hangouts build on top of selenium library.
 It provides ability to create new hangouts, connect to existing calls,
 invite people to call and manage call settings.
 
-Settings API:
-  * :doc:`api/Hangouts`
-  * :doc:`api/Audio`
-  * :doc:`api/Microphone`
-  * :doc:`api/Video`
-  * :doc:`api/Bandwidth`
-
-On Air API:
-  * :doc:`api/Broadcast`
-
-PlugIns API:
-  * :doc:`api/Cameraman`
-  * :doc:`api/Toolbox`
-  * :doc:`api/ControlRoom`
-
 Contents:
 
-.. toctree::
-   :maxdepth: 2
+  .. toctree::
+    :glob:
+
+    api/*
 
-   api_documentation
+Also you can read `developers notes`_
 
+.. _developers notes: DevelopersNotes.html
 
 How to use Hangout API
 ============================================
@@ -60,7 +48,7 @@ Now you can start new or connect and invite people:
     .. doctest:: base_api
 
         >>> hangout.start()
-        >>> hangout.invite(['maxybot@gmail.com', 'test circle for call'])
+        >>> hangout.invite(['maxybot@gmail.com', 'Friends'])
 
 .. Or change call setting, like bandwidth, audio, etc:
 

hangout_api/gadgets/utils.py

@@ -64,7 +64,8 @@ def open_app(self, gadget_name):
 def gadget_context_handler(gadget_name):
     """
     Decorator context handler for gadgets.
-    Make sure that current browser context is set to work with provided PlugIn
+    It makes sure that current browser context is set to work with
+    provided PlugIn.
     """
     def decorator(function):  # pylint: disable=C0111
         @wraps(function)

hangout_api/interfaces.py

@@ -9,23 +9,19 @@
 
 class IModule(Interface):
     """
-    Interface to register utils for hangout instance. Resisted class instance
-    will be reachable as Hangouts class property under the name you registered
-    it.
+    Interface to register extensions for regular hangout call.
+    Resisted class instance will be reachable as Hangouts class property under
+    the name you registered it.
     """
-    # def __init__(self, base):
-    #     pass
-
-    pass
+    def __init__(self, base):
+        pass
 
 
 class IOnAirModule(Interface):
     """
-    Interface to register utils for hangout instance. Resisted class instance
-    will be reachable as Hangouts class property under the name you registered
-    it.
+    Interface to register extensions for hangout OnAir call.
+    Resisted class instance will be reachable as Hangouts class property under
+    the name you registered it.
     """
-    # def __init__(self, base):
-    #     pass
-
-    pass
+    def __init__(self, base):
+        pass

hangout_api/utils.py

@@ -64,6 +64,14 @@ class Utils(object):
     Batch of function to navigate through G+ Hangout to keep main API
     class cleaner
     """
+    browser = None
+    """
+    Instance of the `seleniumwrapper`_ library
+
+    .. _seleniumwrapper: https://pypi.python.org/pypi/seleniumwrapper/
+
+    """
+
     def __init__(self, browser):
         self.browser = browser