Bug 1352023: Fix broken references / typos in Marionette docs; r=whimboo
authorIgnaz Forster <ignaz.forster@gmx.de>
Thu, 08 Jun 2017 23:40:55 +0200
changeset 364200 dc1837d38448
parent 364199 7a729935d60d
child 364201 5e2be621f532
push id44832
push userhskupin@mozilla.com
push dateThu, 15 Jun 2017 22:03:11 +0000
treeherderautoland@dc1837d38448 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerswhimboo
bugs1352023
milestone56.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1352023: Fix broken references / typos in Marionette docs; r=whimboo MozReview-Commit-ID: 6Wo8ewMacjF
testing/marionette/client/docs/advanced/actions.rst
testing/marionette/client/docs/advanced/debug.rst
testing/marionette/client/docs/advanced/findelement.rst
testing/marionette/client/docs/advanced/stale.rst
testing/marionette/client/docs/basics.rst
testing/marionette/client/docs/interactive.rst
testing/marionette/client/docs/reference.rst
testing/marionette/client/marionette_driver/expected.py
testing/marionette/client/marionette_driver/marionette.py
--- a/testing/marionette/client/docs/advanced/actions.rst
+++ b/testing/marionette/client/docs/advanced/actions.rst
@@ -1,23 +1,23 @@
 Actions
 =======
 
-.. py:currentmodule:: marionette
+.. py:currentmodule:: marionette_driver.marionette
 
 Action Sequences
 ----------------
 
 :class:`Actions` are designed as a way to simulate user input as closely as possible
 on a touch device like a smart phone. A common operation is to tap the screen
 and drag your finger to another part of the screen and lift it off.
 
 This can be simulated using an Action::
 
-    from marionette import Actions
+    from marionette_driver.marionette import Actions
 
     start_element = marionette.find_element('id', 'start')
     end_element = marionette.find_element('id', 'end')
 
     action = Actions(marionette)
     action.press(start_element).wait(1).move(end_element).release()
     action.perform()
 
@@ -29,16 +29,18 @@ to a users behaviour.
 Multi-Action Sequences
 ----------------------
 
 Sometimes it may be necessary to simulate multiple actions at the same time.
 For example a user may be dragging one finger while tapping another. This is
 where :class:`MultiActions` come in. MultiActions are simply a way of combining
 two or more actions together and performing them all at the same time::
 
+    from marionette_driver.marionette import Actions, MultiActions
+
     action1 = Actions(marionette)
     action1.press(start_element).move(end_element).release()
 
     action2 = Actions(marionette)
     action2.press(another_element).wait(1).release()
 
     multi = MultiActions(marionette)
     multi.add(action1)
--- a/testing/marionette/client/docs/advanced/debug.rst
+++ b/testing/marionette/client/docs/advanced/debug.rst
@@ -1,30 +1,31 @@
 Debugging
 =========
 
-.. py:currentmodule:: marionette
+.. py:currentmodule:: marionette_driver.marionette
 
 Sometimes when working with Marionette you'll run into unexpected behaviour and
 need to do some debugging. This page outlines some of the Marionette methods
 that can be useful to you.
 
 Please note that the best tools for debugging are the `ones that ship with
 Gecko`_. This page doesn't describe how to use those with Marionette. Also see
 a related topic about `using the debugger with Marionette`_ on MDN.
 
 .. _ones that ship with Gecko: https://developer.mozilla.org/en-US/docs/Tools
 .. _using the debugger with Marionette: https://developer.mozilla.org/en-US/docs/Marionette/Debugging
 
 
 Storing Logs on the Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By calling `~Marionette.log` it is possible to store a message on the server.
-Logs can later be retrieved using `~Marionette.get_logs`. For example::
+By calling :func:`~Marionette.log` it is possible to store a message on the
+server.
+Logs can later be retrieved using :func:`~Marionette.get_logs`. For example::
 
     try:
         marionette.log("Sending a click event") # logged at INFO level
         elem.click()
     except:
         marionette.log("Something went wrong!", "ERROR")
 
     print(marionette.get_logs())
@@ -34,21 +35,21 @@ tracebacks like that!
 
 
 Seeing What's on the Page
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sometimes it's difficult to tell what is actually on the page that is being
 manipulated. Either because it happens too fast, the window isn't big enough or
 you are manipulating a remote server! There are two methods that can help you
-out. The first is `~Marionette.screenshot`::
+out. The first is :func:`~Marionette.screenshot`::
 
     marionette.screenshot() # takes screenshot of entire frame
     elem = marionette.find_element(By.ID, 'some-div')
     marionette.screenshot(elem) # takes a screenshot of only the given element
 
 Sometimes you just want to see the DOM layout. You can do this with the
-`~Marionette.page_source` property. Note that the page source depends on the
-context you are in::
+:attr:`~Marionette.page_source` property. Note that the page source depends on
+the context you are in::
 
     print(marionette.page_source)
     marionette.set_context('chrome')
     print(marionette.page_source)
--- a/testing/marionette/client/docs/advanced/findelement.rst
+++ b/testing/marionette/client/docs/advanced/findelement.rst
@@ -1,11 +1,11 @@
 Finding Elements
 ================
-.. py:currentmodule:: marionette
+.. py:currentmodule:: marionette_driver.marionette
 
 One of the most common and yet often most difficult tasks in Marionette is
 finding a DOM element on a webpage or in the chrome UI. Marionette provides
 several different search strategies to use when finding elements. All search
 strategies work with both :func:`~Marionette.find_element` and
 :func:`~Marionette.find_elements`, though some strategies are not implemented
 in chrome scope.
 
@@ -15,17 +15,17 @@ the event that no elements are matched b
 :func:`~Marionette.find_element` will raise `NoSuchElementException` while
 :func:`~Marionette.find_elements` will return an empty list.
 
 Search Strategies
 -----------------
 
 Search strategies are defined in the :class:`By` class::
 
-    from marionette import By
+    from marionette_driver import By
     print(By.ID)
 
 The strategies are:
 
 * `id` - The easiest way to find an element is to refer to its id directly::
 
         container = client.find_element(By.ID, 'container')
 
--- a/testing/marionette/client/docs/advanced/stale.rst
+++ b/testing/marionette/client/docs/advanced/stale.rst
@@ -1,18 +1,18 @@
 Dealing with Stale Elements
 ===========================
-.. py:currentmodule:: marionette
+.. py:currentmodule:: marionette_driver.marionette
 
 Marionette does not keep a live representation of the DOM saved. All it can do
 is send commands to the Marionette server which queries the DOM on the client's
 behalf. References to elements are also not passed from server to client. A
 unique id is generated for each element that gets referenced and a mapping of
 id to element object is stored on the server. When commands such as
-:func:`~HTMLElement.click()` are run, the client sends the element's id along
+:func:`~HTMLElement.click` are run, the client sends the element's id along
 with the command. The server looks up the proper DOM element in its reference
 table and executes the command on it.
 
 In practice this means that the DOM can change state and Marionette will never
 know until it sends another query. For example, look at the following HTML::
 
     <head>
     <script type=text/javascript>
@@ -34,38 +34,43 @@ The following code has a race condition:
 
     button = client.find_element('id', 'button')
     button.click()
     assert len(client.find_elements('css selector', '#container div')) > 0
 
 
 Explicit Waiting and Expected Conditions
 ----------------------------------------
+.. py:currentmodule:: marionette_driver
 
 To avoid the above scenario, manual synchronisation is needed. 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".
 
 The :class:`Wait` helper class provided by Marionette avoids some of the
 caveats of ``time.sleep(n)``. It will return immediately once the provided
 condition evaluates to true.
 
 To avoid the race condition in the above example, one could do::
 
+    from marionette_driver import Wait
+
     button = client.find_element('id', 'button')
     button.click()
 
     def find_divs():
         return client.find_elements('css selector', '#container div')
 
     divs = Wait(client).until(find_divs)
     assert len(divs) > 0
 
 This avoids the race condition. Because finding elements is a common condition
 to wait for, it is built in to Marionette. Instead of the above, you could
 write::
 
+    from marionette_driver import Wait
+
     button = client.find_element('id', 'button')
     button.click()
     assert len(Wait(client).until(expected.elements_present('css selector', '#container div'))) > 0
 
-For a full list of built-in conditions, see :mod:`~marionette.expected`.
+For a full list of built-in conditions, see :mod:`~marionette_driver.expected`.
--- a/testing/marionette/client/docs/basics.rst
+++ b/testing/marionette/client/docs/basics.rst
@@ -126,17 +126,17 @@ open website, use :func:`~Marionette.get
 DOM Elements
 ------------
 
 In order to inspect or manipulate actual DOM elements, they must first be found
 using the :func:`~Marionette.find_element` or :func:`~Marionette.find_elements`
 methods:
 
 .. parsed-literal::
-   from marionette import HTMLElement
+   from marionette_driver.marionette import HTMLElement
    element = client.find_element(By.ID, 'my-id')
    assert type(element) == HTMLElement
    elements = client.find_elements(By.TAG_NAME, 'a')
    assert type(elements) == list
 
 For a full list of valid search strategies, see :doc:`advanced/findelement`.
 
 Now that an element has been found, it's possible to manipulate it:
--- a/testing/marionette/client/docs/interactive.rst
+++ b/testing/marionette/client/docs/interactive.rst
@@ -7,17 +7,17 @@ Marionette. Let's use a typical python s
 
 .. parsed-literal::
 
    python
 
 First, import Marionette:
 
 .. parsed-literal::
-   from marionette import Marionette
+   from marionette_driver.marionette import Marionette
 
 Now create the client for this session. Assuming you're using the default
 port on a Marionette instance running locally:
 
 .. parsed-literal::
 
    client = Marionette(host='localhost', port=2828)
    client.start_session()
@@ -40,16 +40,16 @@ Now you're at mozilla.org! You can even 
 
 .. parsed-literal::
    client.get_url()
 
 You can even find an element and click on it. Let's say you want to get
 the first link:
 
 .. parsed-literal::
-   from marionette import By
+   from marionette_driver import By
    first_link = client.find_element(By.TAG_NAME, "a")
 
 first_link now holds a reference to the first link on the page. You can click it:
 
 .. parsed-literal::
    first_link.click()
 
--- a/testing/marionette/client/docs/reference.rst
+++ b/testing/marionette/client/docs/reference.rst
@@ -1,51 +1,72 @@
 =============
 API Reference
 =============
 
 Marionette
 ----------
+.. py:currentmodule:: marionette_driver.marionette.Marionette
 .. autoclass:: marionette_driver.marionette.Marionette
    :members:
 
 HTMLElement
 -----------
+.. py:currentmodule:: marionette_driver.marionette.HTMLElement
 .. autoclass:: marionette_driver.marionette.HTMLElement
    :members:
 
 DateTimeValue
 -------------
+.. py:currentmodule:: marionette_driver.DateTimeValue
 .. autoclass:: marionette_driver.DateTimeValue
    :members:
 
 Actions
 -------
+.. py:currentmodule:: marionette_driver.marionette.Actions
 .. autoclass:: marionette_driver.marionette.Actions
    :members:
 
 MultiActions
 ------------
+.. py:currentmodule:: marionette_driver.marionette.MultiActions
 .. autoclass:: marionette_driver.marionette.MultiActions
    :members:
 
+Alert
+-----
+.. py:currentmodule:: marionette_driver.marionette.Alert
+.. autoclass:: marionette_driver.marionette.Alert
+   :members:
+
 Wait
 ----
+.. py:currentmodule:: marionette_driver.Wait
 .. autoclass:: marionette_driver.Wait
    :members:
    :special-members:
 .. autoattribute marionette_driver.wait.DEFAULT_TIMEOUT
 .. autoattribute marionette_driver.wait.DEFAULT_INTERVAL
 
 Built-in Conditions
 ^^^^^^^^^^^^^^^^^^^
+.. py:currentmodule:: marionette_driver.expected
 .. automodule:: marionette_driver.expected
    :members:
 
+Timeouts
+--------
+.. py:currentmodule:: marionette_driver.timeout.Timeouts
+.. autoclass:: marionette_driver.timeout.Timeouts
+   :members:
+
 Addons
 ------
+.. py:currentmodule:: marionette_driver.addons.Addons
 .. autoclass:: marionette_driver.addons.Addons
    :members:
 
 Localization
 ------------
+.. py:currentmodule:: marionette_driver.localization.L10n
 .. autoclass:: marionette_driver.localization.L10n
    :members:
--- a/testing/marionette/client/marionette_driver/expected.py
+++ b/testing/marionette/client/marionette_driver/expected.py
@@ -23,18 +23,18 @@ class element_present(object):
 
     You can select which element to be checked for presence by
     supplying a locator::
 
         el = Wait(marionette).until(expected.element_present(By.ID, "foo"))
 
     Or by using a function/lambda returning an element::
 
-        el = Wait(marionette).\
-                until(expected.element_present(lambda m: m.find_element(By.ID, "foo")))
+        el = Wait(marionette).until(
+            expected.element_present(lambda m: m.find_element(By.ID, "foo")))
 
     :param args: locator or function returning web element
     :returns: the web element once it is located, or False
 
     """
 
     def __init__(self, *args):
         if len(args) == 1 and isinstance(args[0], types.FunctionType):
@@ -52,18 +52,18 @@ class element_not_present(element_presen
 
     You can select which element to be checked for lack of presence by
     supplying a locator::
 
         r = Wait(marionette).until(expected.element_not_present(By.ID, "foo"))
 
     Or by using a function/lambda returning an element::
 
-        r = Wait(marionette).\
-                until(expected.element_present(lambda m: m.find_element(By.ID, "foo")))
+        r = Wait(marionette).until(
+            expected.element_present(lambda m: m.find_element(By.ID, "foo")))
 
     :param args: locator or function returning web element
     :returns: True if element is not present, or False if it is present
 
     """
 
     def __init__(self, *args):
         super(element_not_present, self).__init__(*args)
@@ -110,18 +110,18 @@ class elements_present(object):
 
     You can select which elements to be checked for presence by
     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::
 
-        els = Wait(marionette).\
-                until(expected.elements_present(lambda m: m.find_elements(By.TAG_NAME, "a")))
+        els = Wait(marionette).until(
+            expected.elements_present(lambda m: m.find_elements(By.TAG_NAME, "a")))
 
     :param args: locator or function returning a list of web elements
     :returns: list of web elements once they are located, or False
 
     """
 
     def __init__(self, *args):
         if len(args) == 1 and isinstance(args[0], types.FunctionType):
@@ -139,18 +139,18 @@ class elements_not_present(elements_pres
 
     You can select which elements to be checked for not being present
     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::
 
-        r = Wait(marionette).\
-                until(expected.elements_not_present(lambda m: m.find_elements(By.TAG_NAME, "a")))
+        r = Wait(marionette).until(
+            expected.elements_not_present(lambda m: m.find_elements(By.TAG_NAME, "a")))
 
     :param args: locator or function returning a list of web elements
     :returns: True if elements are missing, False if one or more are
         present
 
     """
 
     def __init__(self, *args):
@@ -164,17 +164,18 @@ class element_displayed(object):
     """An expectation for checking that an element is visible.
 
     Visibility means that the element is not only displayed, but also
     has a height and width that is greater than 0 pixels.
 
     Stale elements, meaning elements that have been detached from the
     DOM of the current context are treated as not being displayed,
     meaning this expectation is not analogous to the behaviour of
-    calling `is_displayed()` on an `HTMLElement`.
+    calling :func:`~marionette_driver.marionette.HTMLElement.is_displayed`
+    on an :class:`~marionette_driver.marionette.HTMLElement`.
 
     You can select which element to be checked for visibility by
     supplying a locator::
 
         displayed = Wait(marionette).until(expected.element_displayed(By.ID, "foo"))
 
     Or by supplying an element::
 
@@ -208,17 +209,18 @@ class element_not_displayed(element_disp
     """An expectation for checking that an element is not visible.
 
     Visibility means that the element is not only displayed, but also
     has a height and width that is greater than 0 pixels.
 
     Stale elements, meaning elements that have been detached fom the
     DOM of the current context are treated as not being displayed,
     meaning this expectation is not analogous to the behaviour of
-    calling `is_displayed()` on an `HTMLElement`.
+    calling :func:`~marionette_driver.marionette.HTMLElement.is_displayed`
+    on an :class:`~marionette_driver.marionette.HTMLElement`.
 
     You can select which element to be checked for visibility by
     supplying a locator::
 
         hidden = Wait(marionette).until(expected.element_not_displayed(By.ID, "foo"))
 
     Or by supplying an element::
 
--- a/testing/marionette/client/marionette_driver/marionette.py
+++ b/testing/marionette/client/marionette_driver/marionette.py
@@ -39,26 +39,28 @@ class HTMLElement(object):
 
     def __eq__(self, other_element):
         return self.id == other_element.id
 
     def find_element(self, method, target):
         """Returns an ``HTMLElement`` instance that matches the specified
         method and target, relative to the current element.
 
-        For more details on this function, see the `find_element` method
+        For more details on this function, see the
+        :func:`~marionette_driver.marionette.Marionette.find_element` method
         in the Marionette class.
         """
         return self.marionette.find_element(method, target, self.id)
 
     def find_elements(self, method, target):
         """Returns a list of all ``HTMLElement`` instances that match the
         specified method and target in the current context.
 
-        For more details on this function, see the find_elements method
+        For more details on this function, see the
+        :func:`~marionette_driver.marionette.Marionette.find_elements` method
         in the Marionette class.
         """
         return self.marionette.find_elements(method, target, self.id)
 
     def get_attribute(self, name):
         """Returns the requested attribute, or None if no attribute
         is set.
         """
@@ -74,16 +76,17 @@ class HTMLElement(object):
             return self.marionette._send_message("getElementProperty", body, key="value")
         except errors.UnknownCommandException:
             # Keep backward compatibility for code which uses get_attribute() to
             # also retrieve element properties.
             # Remove when Firefox 55 is stable.
             return self.get_attribute(name)
 
     def click(self):
+        """Simulates a click on the element."""
         self.marionette._send_message("clickElement", {"id": self.id})
 
     def tap(self, x=None, y=None):
         """Simulates a set of tap events on the element.
 
         :param x: X coordinate of tap event.  If not given, default to
             the centre of the element.
         :param y: Y coordinate of tap event. If not given, default to
@@ -242,17 +245,17 @@ class Actions(object):
         element = element.id
         self.action_chain.append(['press', element, x, y])
         return self
 
     def release(self):
         '''
         Sends a 'touchend' event to this element.
 
-        May only be called if press() has already be called on this element.
+        May only be called if :func:`press` has already be called on this element.
 
         If press and release are chained without a move action between them,
         then it will be processed as a 'tap' event, and will dispatch the
         expected mouse events ('mousemove' (if necessary), 'mousedown',
         'mouseup', 'mouseclick') after the touch events. If there is a wait
         period between press and release that will trigger a contextmenu,
         then the 'contextmenu' menu event will be fired instead of the
         touch/mouse events.
@@ -261,28 +264,28 @@ class Actions(object):
         return self
 
     def move(self, element):
         '''
         Sends a 'touchmove' event at the center of the target element.
 
         :param element: Element to move towards.
 
-        May only be called if press() has already be called.
+        May only be called if :func:`press` has already be called.
         '''
         element = element.id
         self.action_chain.append(['move', element])
         return self
 
     def move_by_offset(self, x, y):
         '''
         Sends 'touchmove' event to the given x, y coordinates relative to the
         top-left of the currently touched element.
 
-        May only be called if press() has already be called.
+        May only be called if :func:`press` has already be called.
 
         :param x: Specifies x-coordinate of move event, relative to the
          top-left corner of the element.
         :param y: Specifies y-coordinate of move event, relative to the
          top-left corner of the element.
         '''
         self.action_chain.append(['moveByOffset', x, y])
         return self
@@ -298,17 +301,17 @@ class Actions(object):
         '''
         self.action_chain.append(['wait', time])
         return self
 
     def cancel(self):
         '''
         Sends 'touchcancel' event to the target of the original 'touchstart' event.
 
-        May only be called if press() has already be called.
+        May only be called if :func:`press` has already be called.
         '''
         self.action_chain.append(['cancel'])
         return self
 
     def tap(self, element, x=None, y=None):
         '''
         Performs a quick tap on the target element.
 
@@ -450,16 +453,17 @@ class Actions(object):
         """
         self.action_chain.append(['keyDown', key_code])
         return self
 
     def key_up(self, key_code):
         """
         Perform a "keyUp" action for the given key code. Modifier keys are
         respected by the server for the course of an action chain.
+
         :param key_up: The key to release as a result of this action.
         """
         self.action_chain.append(['keyUp', key_code])
         return self
 
     def perform(self):
         """Sends the action chain built so far to the server side for
         execution and clears the current chain of actions."""
@@ -860,16 +864,17 @@ class Marionette(object):
         :param default_branch: Optional, if `True` the preference value will be read
                                from the default branch. Otherwise the user-defined
                                value if set is returned. Defaults to `False`.
         :param value_type: Optional, XPCOM interface of the pref's complex value.
                            Defaults to `nsISupportsString`. Other possible values are:
                            `nsILocalFile`, and `nsIPrefLocalizedString`.
 
         Usage example::
+
             marionette.get_pref("browser.tabs.warnOnClose")
 
         """
         with self.using_context(self.CONTEXT_CHROME):
             pref_value = self.execute_script("""
                 Components.utils.import("resource://gre/modules/Preferences.jsm");
 
                 let pref = arguments[0];
@@ -889,16 +894,17 @@ class Marionette(object):
                       reset the preference to its default value. If no default
                       value exists, the preference will cease to exist.
         :param default_branch: Optional, if `True` the preference value will
                        be written to the default branch, and will remain until
                        the application gets restarted. Otherwise a user-defined
                        value is set. Defaults to `False`.
 
         Usage example::
+
             marionette.set_pref("browser.tabs.warnOnClose", True)
 
         """
         with self.using_context(self.CONTEXT_CHROME):
             if value is None:
                 self.clear_pref(pref)
                 return
 
@@ -912,17 +918,17 @@ class Marionette(object):
                 prefs = new Preferences({defaultBranch: defaultBranch});
                 prefs.set(pref, value);
                 """, script_args=(pref, value, default_branch))
 
     def set_prefs(self, prefs, default_branch=False):
         """Set the value of a list of preferences.
 
         :param prefs: A dict containing one or more preferences and their values
-                      to be set. See `set_pref` for further details.
+                      to be set. See :func:`set_pref` for further details.
         :param default_branch: Optional, if `True` the preference value will
                        be written to the default branch, and will remain until
                        the application gets restarted. Otherwise a user-defined
                        value is set. Defaults to `False`.
 
         Usage example::
 
             marionette.set_prefs({"browser.tabs.warnOnClose": True})
@@ -931,17 +937,17 @@ class Marionette(object):
         for pref, value in prefs.items():
             self.set_pref(pref, value, default_branch=default_branch)
 
     @contextmanager
     def using_prefs(self, prefs, default_branch=False):
         """Set preferences for code executed in a `with` block, and restores them on exit.
 
         :param prefs: A dict containing one or more preferences and their values
-                      to be set. See `set_prefs` for further details.
+                      to be set. See :func:`set_prefs` for further details.
         :param default_branch: Optional, if `True` the preference value will
                        be written to the default branch, and will remain until
                        the application gets restarted. Otherwise a user-defined
                        value is set. Defaults to `False`.
 
         Usage example::
 
             with marionette.using_prefs({"browser.tabs.warnOnClose": True}):
@@ -957,17 +963,17 @@ class Marionette(object):
             self.set_prefs(original_prefs, default_branch=default_branch)
 
     @do_process_check
     def enforce_gecko_prefs(self, prefs):
         """Checks if the running instance has the given prefs. If not,
         it will kill the currently running instance, and spawn a new
         instance with the requested preferences.
 
-        : param prefs: A dictionary whose keys are preference names.
+        :param prefs: A dictionary whose keys are preference names.
         """
         if not self.instance:
             raise errors.MarionetteException("enforce_gecko_prefs() can only be called "
                                              "on Gecko instances launched by Marionette")
         pref_exists = True
         with self.using_context(self.CONTEXT_CHROME):
             for pref, value in prefs.iteritems():
                 if type(value) is not str:
@@ -1058,17 +1064,17 @@ class Marionette(object):
         self._send_message("quitApplication", body)
 
     @do_process_check
     def quit(self, in_app=False, callback=None):
         """Terminate the currently running instance.
 
         This command will delete the active marionette session. It also allows
         manipulation of eg. the profile data while the application is not running.
-        To start the application again, start_session() has to be called.
+        To start the application again, :func:`start_session` has to be called.
 
         :param in_app: If True, marionette will cause a quit from within the
                        browser. Otherwise the browser will be quit immediately
                        by killing the process.
         :param callback: If provided and `in_app` is True, the callback will
                          be used to trigger the shutdown.
         """
         if not self.instance:
@@ -1218,21 +1224,21 @@ class Marionette(object):
     @test_name.setter
     def test_name(self, test_name):
         self._test_name = test_name
 
     def delete_session(self, send_request=True, reset_session_id=False):
         """Close the current session and disconnect from the server.
 
         :param send_request: Optional, if `True` a request to close the session on
-            the server side will be send. Use `False` in case of eg. in_app restart()
+            the server side will be sent. Use `False` in case of eg. in_app restart()
             or quit(), which trigger a deletion themselves. Defaults to `True`.
         :param reset_session_id: Optional, if `True` the current session id will
-            be reset, which will require an explicit call to `start_session()` before
-            the test can continue. Defaults to `False`.
+            be reset, which will require an explicit call to :func:`start_session`
+            before the test can continue. Defaults to `False`.
         """
         try:
             if send_request:
                 self._send_message("deleteSession")
         finally:
             if reset_session_id:
                 self.session_id = None
             self.session = None
@@ -1251,37 +1257,36 @@ class Marionette(object):
         """
         return self.session
 
     def set_script_timeout(self, timeout):
         """Sets the maximum number of ms that an asynchronous script is
         allowed to run.
 
         If a script does not return in the specified amount of time,
-        a ScriptTimeoutException is raised.
+        a ``ScriptTimeoutException`` is raised.
 
         :param timeout: The maximum number of milliseconds an asynchronous
-            script can run without causing an ScriptTimeoutException to
+            script can run without causing an ``ScriptTimeoutException`` to
             be raised
 
         .. note:: `set_script_timeout` is deprecated, please use
             `timeout.script` setter.
 
         """
         warnings.warn(
             "set_script_timeout is deprecated, please use timeout.script setter",
             DeprecationWarning)
         self.timeout.script = timeout / 1000
 
     def set_search_timeout(self, timeout):
         """Sets a timeout for the find methods.
 
-        When searching for an element using
-        either :class:`Marionette.find_element` or
-        :class:`Marionette.find_elements`, the method will continue
+        When searching for an element using either :func:`find_element` or
+        :func:`find_elements`, the method will continue
         trying to locate the element for up to timeout ms. This can be
         useful if, for example, the element you're looking for might
         not exist immediately, because it belongs to a page which is
         currently being loaded.
 
         :param timeout: Timeout in milliseconds.
 
         .. note:: `set_search_timeout` is deprecated, please use
@@ -1474,18 +1479,18 @@ class Marionette(object):
         scope = self._send_message("getContext", key="value")
         self.set_context(context)
         try:
             yield
         finally:
             self.set_context(scope)
 
     def switch_to_alert(self):
-        """Returns an Alert object for interacting with a currently
-        displayed alert.
+        """Returns an :class:`~marionette_driver.marionette.Alert` object for
+        interacting with a currently displayed alert.
 
         ::
 
             alert = self.marionette.switch_to_alert()
             text = alert.text
             alert.accept()
         """
         return Alert(self)
@@ -1499,18 +1504,18 @@ class Marionette(object):
         :param focus: A boolean value which determins whether to focus
             the window that we just switched to.
         """
         body = {"focus": focus, "name": window_id}
         self._send_message("switchToWindow", body)
         self.window = window_id
 
     def get_active_frame(self):
-        """Returns an HTMLElement representing the frame Marionette is
-        currently acting on."""
+        """Returns an :class:`~marionette_driver.marionette.HTMLElement`
+        representing the frame Marionette is currently acting on."""
         return self._send_message("getActiveFrame", key="value")
 
     def switch_to_default_content(self):
         """Switch the current context to page's default content."""
         return self.switch_to_frame()
 
     def switch_to_parent_frame(self):
         """
@@ -1519,17 +1524,18 @@ class Marionette(object):
         self._send_message("switchToParentFrame")
 
     def switch_to_frame(self, frame=None, focus=True):
         """Switch the current context to the specified frame. Subsequent
         commands will operate in the context of the specified frame,
         if applicable.
 
         :param frame: A reference to the frame to switch to.  This can
-            be an ``HTMLElement``, an integer index, string name, or an
+            be an :class:`~marionette_driver.marionette.HTMLElement`,
+            an integer index, string name, or an
             ID attribute.  If you call ``switch_to_frame`` without an
             argument, it will switch to the top-level frame.
 
         :param focus: A boolean value which determins whether to focus
             the frame that we just switched to.
         """
         body = {"focus": focus}
         if isinstance(frame, HTMLElement):
@@ -1539,19 +1545,19 @@ class Marionette(object):
         self._send_message("switchToFrame", body)
 
     def switch_to_shadow_root(self, host=None):
         """Switch the current context to the specified host's Shadow DOM.
         Subsequent commands will operate in the context of the specified Shadow
         DOM, if applicable.
 
         :param host: A reference to the host element containing Shadow DOM.
-            This can be an ``HTMLElement``. If you call
-            ``switch_to_shadow_root`` without an argument, it will switch to the
-            parent Shadow DOM or the top-level frame.
+            This can be an :class:`~marionette_driver.marionette.HTMLElement`.
+            If you call ``switch_to_shadow_root`` without an argument, it will
+            switch to the parent Shadow DOM or the top-level frame.
         """
         body = {}
         if isinstance(host, HTMLElement):
             body["id"] = host.id
         return self._send_message("switchToShadowRoot", body)
 
     def get_url(self):
         """Get a string representing the current URL.
@@ -1586,20 +1592,20 @@ class Marionette(object):
         The command will return with a failure if there is an error
         loading the document or the URL is blocked.  This can occur if
         it fails to reach the host, the URL is malformed, the page is
         restricted (about:* pages), or if there is a certificate issue
         to name some examples.
 
         The document is considered successfully loaded when the
         `DOMContentLoaded` event on the frame element associated with the
-        `window` triggers and `document.readState` is "complete".
+        `window` triggers and `document.readyState` is "complete".
 
         In chrome context it will change the current `window`'s location
-        to the supplied URL and wait until `document.readState` equals
+        to the supplied URL and wait until `document.readyState` equals
         "complete" or the page timeout duration has elapsed.
 
         :param url: The URL to navigate to.
         """
         self._send_message("get", {"url": url})
 
     def go_back(self):
         """Causes the browser to perform a back navigation."""
@@ -1667,18 +1673,18 @@ class Marionette(object):
         return self._from_json(rv)
 
     def execute_script(self, script, script_args=(), new_sandbox=True,
                        sandbox="default", script_timeout=None):
         """Executes a synchronous JavaScript script, and returns the
         result (or None if the script does return a value).
 
         The script is executed in the context set by the most recent
-        set_context() call, or to the CONTEXT_CONTENT context if set_context()
-        has not been called.
+        :func:`set_context` call, or to the CONTEXT_CONTENT context if
+        :func:`set_context` has not been called.
 
         :param script: A string containing the JavaScript to execute.
         :param script_args: An interable of arguments to pass to the script.
         :param sandbox: A tag referring to the sandbox you wish to use;
             if you specify a new tag, a new sandbox will be created.
             If you use the special tag `system`, the sandbox will
             be created using the system principal which has elevated
             privileges.
@@ -1714,17 +1720,17 @@ class Marionette(object):
               window.wrappedJSObject.test1 = "foo";
               window.wrappedJSObject.test2 = "bar";
               return window.wrappedJSObject.test1 + window.wrappedJSObject.test2;
               ''')
             assert result == "foobar"
 
         Global variables set by individual scripts do not persist between
         script calls by default.  If you wish to persist data between
-        script calls, you can set new_sandbox to False on your next call,
+        script calls, you can set `new_sandbox` to False on your next call,
         and add any new variables to a new 'global' object like this:
 
         ::
 
             marionette.execute_script("global.test1 = 'foo';")
             result = self.marionette.execute_script("return global.test1;", new_sandbox=False)
             assert result == "foo"
 
@@ -1744,18 +1750,18 @@ class Marionette(object):
 
     def execute_async_script(self, script, script_args=(), new_sandbox=True,
                              sandbox="default", script_timeout=None,
                              debug_script=False):
         """Executes an asynchronous JavaScript script, and returns the
         result (or None if the script does return a value).
 
         The script is executed in the context set by the most recent
-        set_context() call, or to the CONTEXT_CONTENT context if
-        set_context() has not been called.
+        :func:`set_context` call, or to the CONTEXT_CONTENT context if
+        :func:`set_context` has not been called.
 
         :param script: A string containing the JavaScript to execute.
         :param script_args: An interable of arguments to pass to the script.
         :param sandbox: A tag referring to the sandbox you wish to use; if
             you specify a new tag, a new sandbox will be created.  If you
             use the special tag `system`, the sandbox will be created
             using the system principal which has elevated privileges.
         :param new_sandbox: If False, preserve global variables from
@@ -1787,25 +1793,28 @@ class Marionette(object):
                 "scriptTimeout": script_timeout,
                 "line": int(frame[1]),
                 "filename": os.path.basename(frame[0]),
                 "debug_script": debug_script}
         rv = self._send_message("executeAsyncScript", body, key="value")
         return self._from_json(rv)
 
     def find_element(self, method, target, id=None):
-        """Returns an HTMLElement instances that matches the specified
-        method and target in the current context.
+        """Returns an :class:`~marionette_driver.marionette.HTMLElement`
+        instance that matches the specified method and target in the current
+        context.
 
-        An HTMLElement instance may be used to call other methods on the
-        element, such as click().  If no element is immediately found, the
-        attempt to locate an element will be repeated for up to the amount of
-        time set by ``timeout.implicit``. If multiple elements match the given
-        criteria, only the first is returned. If no element matches, a
-        NoSuchElementException will be raised.
+        An :class:`~marionette_driver.marionette.HTMLElement` instance may be
+        used to call other methods on the element, such as
+        :func:`~marionette_driver.marionette.HTMLElement.click`.  If no element
+        is immediately found, the attempt to locate an element will be repeated
+        for up to the amount of time set by
+        :attr:`marionette_driver.timeout.Timeouts.implicit`. If multiple
+        elements match the given criteria, only the first is returned. If no
+        element matches, a ``NoSuchElementException`` will be raised.
 
         :param method: The method to use to locate the element; one of:
             "id", "name", "class name", "tag name", "css selector",
             "link text", "partial link text", "xpath", "anon" and "anon
             attribute". Note that the "name", "link text" and "partial
             link test" methods are not supported in the chrome DOM.
         :param target: The target of the search.  For example, if method =
             "tag", target might equal "div".  If method = "id", target would
@@ -1814,23 +1823,26 @@ class Marionette(object):
             with the specified id.
         """
         body = {"value": target, "using": method}
         if id:
             body["element"] = id
         return self._send_message("findElement", body, key="value")
 
     def find_elements(self, method, target, id=None):
-        """Returns a list of all HTMLElement instances that match the
-        specified method and target in the current context.
+        """Returns a list of all
+        :class:`~marionette_driver.marionette.HTMLElement` instances that match
+        the specified method and target in the current context.
 
-        An HTMLElement instance may be used to call other methods on the
-        element, such as click().  If no element is immediately found,
-        the attempt to locate an element will be repeated for up to the
-        amount of time set by ``timeout.implicit``.
+        An :class:`~marionette_driver.marionette.HTMLElement` instance may be
+        used to call other methods on the element, such as
+        :func:`~marionette_driver.marionette.HTMLElement.click`.  If no element
+        is immediately found, the attempt to locate an element will be repeated
+        for up to the amount of time set by
+        :attr:`marionette_driver.timeout.Timeouts.implicit`.
 
         :param method: The method to use to locate the elements; one
             of: "id", "name", "class name", "tag name", "css selector",
             "link text", "partial link text", "xpath", "anon" and "anon
             attribute". Note that the "name", "link text" and "partial link
             test" methods are not supported in the chrome DOM.
         :param target: The target of the search.  For example, if method =
             "tag", target might equal "div".  If method = "id", target would be
@@ -1951,18 +1963,19 @@ class Marionette(object):
         as a base 64 string by default. If the `element` argument is defined the
         capture area will be limited to the bounding box of that
         element.  Otherwise, the capture area will be the bounding box
         of the current frame.
 
         :param element: The element to take a screenshot of.  If None, will
             take a screenshot of the current frame.
 
-        :param highlights: A list of HTMLElement objects to draw a red
-            box around in the returned screenshot.
+        :param highlights: A list of
+            :class:`~marionette_driver.marionette.HTMLElement` objects to draw
+            a red box around in the returned screenshot.
 
         :param format: if "base64" (the default), returns the screenshot
             as a base64-string. If "binary", the data is decoded and
             returned as raw binary. If "hash", the data is hashed using
             the SHA-256 algorithm and the result is returned as a hex digest.
 
         :param full: If True (the default), the capture area will be the
             complete frame. Else only the viewport is captured. Only applies
@@ -2053,17 +2066,17 @@ class Marionette(object):
         """
         warnings.warn("set_window_size() has been deprecated, please use set_window_rect()",
                       DeprecationWarning)
         body = {"width": width, "height": height}
         return self._send_message("setWindowSize", body)
 
     def maximize_window(self):
         """ Resize the browser window currently receiving commands. The action
-        should be equivalent to the user pressing the the maximize button
+        should be equivalent to the user pressing the maximize button
         """
         return self._send_message("maximizeWindow")
 
     def fullscreen(self):
         """ Synchronously sets the user agent window to full screen as if the user
         had done "View > Enter Full Screen",  or restores it if it is already
         in full screen.