Merge 5375b19 into e667b38

docs/api.rst

@@ -0,0 +1,32 @@
+Developer Interface
+*******************
+
+This part of the documentation describes the interfaces for using FoxPuppet.
+
+FoxPuppet
+---------
+
+.. py:module:: foxpuppet.foxpuppet
+
+.. autoclass:: FoxPuppet
+
+
+Windows
+-------
+
+This module contains all of the window types as well as the window manager.
+
+Window Manager
+==============
+
+.. py:module:: foxpuppet.windows
+
+.. autoclass:: WindowManager
+
+Browser Window
+==============
+
+.. py:module:: foxpuppet.windows.browser.window
+
+.. autoclass:: BrowserWindow
+  :inherited-members:

docs/conf.py

@@ -17,9 +17,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- General configuration ------------------------------------------------
@@ -31,9 +31,16 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc',
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
     'sphinx.ext.todo',
-    'sphinx.ext.viewcode']
+    ]
+
+# intersphinx mappings
+intersphinx_mapping = {
+    'selenium': ('http://seleniumhq.github.io/selenium/docs/api/py/', None)}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -11,3 +11,4 @@ FoxPuppet is a library for automating user interactions in `Firefox <https://www
    user_guide
    development
    news
+   api

foxpuppet/foxpuppet.py

@@ -8,7 +8,13 @@
 
 
 class FoxPuppet(object):
-    """ Class that sets up the api for interacting with the Firefox browser.
+    """
+        Class that sets up the interface for interacting with the Firefox
+        browser.
+
+        :param selenium: WebDriver object
+        :type selenium:
+            :py:class:`~selenium.webdriver.remote.webdriver.WebDriver`
     """
 
     def __init__(self, selenium):

foxpuppet/windows/base.py

@@ -8,6 +8,16 @@
 
 class BaseWindow(object):
 
+    """
+        A base window model.
+
+        :param selenium: WebDriver object.
+        :type selenium:
+            :py:class:`~selenium.webdriver.remote.webdriver.WebDriver`
+        :param handle: A window handle.
+        :type handle: str
+    """
+
     _document_element = (By.CSS_SELECTOR, ':root')
 
     def __init__(self, selenium, handle):
@@ -19,7 +29,9 @@ def __init__(self, selenium, handle):
     def document_element(self):
         """ Returns the inner DOM window element.
 
-        :returns: DOM window element.
+        :return: DOM window element.
+        :return type:
+            :py:class:`~selenium.webdriver.remote.webdriver.WebDriver` locator
         """
 
         return self.selenium.find_element(*self._document_element)
@@ -35,12 +47,11 @@ def firefox_version(self):
         return int(version.partition('.')[0])
 
     def close(self):
-        """Closes the window"""
-
+        """Closes the window."""
         self.switch_to()
         self.selenium.close()
 
     def switch_to(self):
-        """Switches to the window"""
+        """Switches focus for Selenium commands to this window."""
 
         self.selenium.switch_to.window(self.handle)

foxpuppet/windows/browser/window.py

@@ -12,7 +12,8 @@
 
 class BrowserWindow(BaseWindow):
 
-    """Representation of a browser window."""
+    """Representation of a browser window.
+    """
 
     _file_menu_button_locator = (By.ID, 'file-menu')
     _file_menu_private_window_locator = (By.ID, 'menu_newPrivateWindow')
@@ -56,7 +57,12 @@ def wait_for_notification(self, notification_class=BaseNotification):
 
     @property
     def is_private(self):
-        """Returns True if this is a Private Browsing window."""
+        """
+            Property that checks if the specified window is private or not.
+
+            :returns: True if this is a Private Browsing window.
+            :return type: bool
+        """
 
         self.switch_to()
         with self.selenium.context(self.selenium.CONTEXT_CHROME):
@@ -73,6 +79,12 @@ def open_window(self, private=False):
 
         :param private: Optional parameter to open a private browsing window.
                         Defaults to False.
+        :type private: bool
+
+        :returns:
+            :py:class:`~foxpuppet.windows.browser.window.BrowserWindow`
+            object of the newly opened window.
+        :return type: object
         """
 
         handles_before = self.selenium.window_handles

foxpuppet/windows/manager.py

@@ -5,14 +5,27 @@
 
 class WindowManager(object):
 
+    """
+        A window manager that controls the creation of window objects
+        for interaction.
+
+        :param selenium: WebDriver object.
+        :type selenium:
+            :py:class:`~selenium.webdriver.remote.webdriver.WebDriver`
+    """
+
     def __init__(self, selenium):
         self.selenium = selenium
 
     @property
     def windows(self):
         """
-        Sets all current window handles to appropriate window instances
-        :returns: A list of BrowserWindow Instances
+        Returns a list of all open windows
+
+        :returns: :py:class:`~foxpuppet.windows.browser.window.BrowserWindow`
+            objects.
+        :return type: list
+
         """
         from foxpuppet.windows import BrowserWindow
         return [BrowserWindow(self.selenium, handle)