Bug 1081139 - Document Marionette's wait and expected modules. r=ahal

testing/marionette/client/docs/conf.py

@@ -124,7 +124,7 @@ html_theme = 'default'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

testing/marionette/client/docs/index.rst

@@ -100,7 +100,7 @@ Marionette Objects
 .. autoclass:: Marionette
 
 Session Management
-``````````````````
+^^^^^^^^^^^^^^^^^^
 .. automethod:: Marionette.start_session
 .. automethod:: Marionette.delete_session
 .. autoattribute:: Marionette.session_capabilities
@@ -110,7 +110,7 @@ Session Management
 .. automethod:: Marionette.delete_all_cookies
 
 Context Management
-``````````````````
+^^^^^^^^^^^^^^^^^^
 .. autoattribute:: Marionette.current_window_handle
 .. autoattribute:: Marionette.window_handles
 .. automethod:: Marionette.set_context
@@ -120,7 +120,7 @@ Context Management
 .. automethod:: Marionette.close
 
 Navigation Methods
-``````````````````
+^^^^^^^^^^^^^^^^^^
 .. autoattribute:: Marionette.title
 .. automethod:: Marionette.navigate
 .. automethod:: Marionette.get_url
@@ -131,19 +131,19 @@ Navigation Methods
 .. automethod:: Marionette.get_window_type
 
 DOM Element Methods
-```````````````````
+^^^^^^^^^^^^^^^^^^^
 .. automethod:: Marionette.set_search_timeout
 .. automethod:: Marionette.find_element
 .. automethod:: Marionette.find_elements
 
 Script Execution
-````````````````
+^^^^^^^^^^^^^^^^
 .. automethod:: Marionette.execute_script
 .. automethod:: Marionette.execute_async_script
 .. automethod:: Marionette.set_script_timeout
 
 Debugging
-`````````
+^^^^^^^^^
 .. autoattribute:: Marionette.page_source
 .. automethod:: Marionette.log
 .. automethod:: Marionette.get_logs
@@ -152,7 +152,6 @@ Debugging
 Querying and Modifying Document Content
 ---------------------------------------
 .. autoclass:: HTMLElement
-
 .. autoattribute:: HTMLElement.text
 .. autoattribute:: HTMLElement.location
 .. autoattribute:: HTMLElement.size
@@ -166,7 +165,6 @@ Querying and Modifying Document Content
 .. automethod:: HTMLElement.value_of_css_property
 
 .. autoclass:: DateTimeValue
-
 .. autoattribute:: DateTimeValue.date
 .. autoattribute:: DateTimeValue.time
 
@@ -174,9 +172,8 @@ Action Objects
 --------------
 
 Action Sequences
-````````````````
+^^^^^^^^^^^^^^^^
 .. autoclass:: Actions
-
 .. automethod:: Actions.press
 .. automethod:: Actions.release
 .. automethod:: Actions.move
@@ -190,12 +187,52 @@ Action Sequences
 .. automethod:: Actions.perform
 
 Multi-action Sequences
-``````````````````````
+^^^^^^^^^^^^^^^^^^^^^^
 .. autoclass:: MultiActions
-
 .. automethod:: MultiActions.add
 .. automethod:: MultiActions.perform
 
+Explicit Waiting and Expected Conditions
+----------------------------------------
+
+Waits are used to pause program execution
+until a given condition is true.
+This is a useful technique to employ
+when documents load new content or change
+after ``Document.readyState``'s value changes to "complete".
+
+Because Marionette returns control to the user
+when the document is completely loaded,
+any subsequent interaction with elements
+are subject to manual synchronisation.
+The reason for this is that Marionette
+does not keep a direct representation of the DOM,
+but instead exposes a way for the user to
+query the browser's DOM state.
+
+The `Wait` helper class provided by Marionette
+avoids some of the caveats of ``time.sleep(n)``,
+which sets the condition to an exact time period to wait.
+It will return immediately
+once the provided condition evaluates to true.
+
+In addition to writing your own custom conditions
+you can combine `Wait`
+with a number of ready-made expected conditions
+that are listed below.
+
+Waits
+^^^^^
+.. autoclass:: marionette.wait.Wait
+   :members:
+   :special-members:
+.. autoattribute marionette.wait.DEFAULT_TIMEOUT
+.. autoattribute marionette.wait.DEFAULT_INTERVAL
+
+Expected Conditions
+^^^^^^^^^^^^^^^^^^^
+.. automodule:: marionette.expected
+   :members:
 
 Indices and tables
 ==================

testing/marionette/client/marionette/expected.py

@@ -19,11 +19,11 @@ class element_present(object):
     visible.
 
     You can select which element to be checked for presence by
-    supplying a locator:
+    supplying a locator::
 
         el = Wait(marionette).until(expected.element_present(By.ID, "foo"))
 
-    Or by using a function/lambda returning an element:
+    Or by using a function/lambda returning an element::
 
         el = Wait(marionette).until(expected.element_present(lambda m: m.find_element(By.ID, "foo")))
 
@@ -46,11 +46,11 @@ class element_not_present(element_present):
     context.
 
     You can select which element to be checked for lack of presence by
-    supplying a locator:
+    supplying a locator::
 
         r = Wait(marionette).until(expected.element_not_present(By.ID, "foo"))
 
-    Or by using a function/lambda returning an element:
+    Or by using a function/lambda returning an element::
 
         r = Wait(marionette).until(expected.element_present(lambda m: m.find_element(By.ID, "foo")))
 
@@ -72,7 +72,7 @@ class element_stale(object):
     This can be useful for waiting until an element is no longer
     present.
 
-    Sample usage:
+    Sample usage::
 
         el = marionette.find_element(By.ID, "foo")
         # ...
@@ -101,11 +101,11 @@ class elements_present(object):
     visible.
 
     You can select which elements to be checked for presence by
-    supplying a locator:
+    supplying a locator::
 
         els = Wait(marionette).until(expected.elements_present(By.TAG_NAME, "a"))
 
-    Or by using a function/lambda returning a list of elements:
+    Or by using a function/lambda returning a list of elements::
 
         els = Wait(marionette).until(expected.elements_present(lambda m: m.find_elements(By.TAG_NAME, "a")))
 
@@ -128,11 +128,11 @@ class elements_not_present(elements_present):
     current context.
 
     You can select which elements to be checked for not being present
-    by supplying a locator:
+    by supplying a locator::
 
         r = Wait(marionette).until(expected.elements_not_present(By.TAG_NAME, "a"))
 
-    Or by using a function/lambda returning a list of elements:
+    Or by using a function/lambda returning a list of elements::
 
         r = Wait(marionette).until(expected.elements_not_present(lambda m: m.find_elements(By.TAG_NAME, "a")))
 
@@ -214,7 +214,7 @@ class element_not_selected(element_selected):
     selected.
 
     :param element: the element to not be selected
-    :returns True if element is not selected, False if selected
+    :returns: True if element is not selected, False if selected
 
     """
 

testing/marionette/client/marionette/wait.py

@@ -35,7 +35,7 @@ class Wait(object):
         implementation than the one provided by the standard library
         (time) can also be provided.
 
-        Sample usage:
+        Sample usage::
 
             # Wait 30 seconds for window to open, checking for its presence once
             # every 5 seconds.