Merge pull request #119 from OpenTrons/docs-edits

Docs edits

Author: andySigler

docs/source/getting_started.rst

@@ -30,6 +30,7 @@ Now that you've installed Opentrons API on your computer, you have access to a v
 
   from opentrons import robot, instruments, containers
   robot.reset()
+  robot.connect()
   i = 0
 
   tiprack = containers.load(
@@ -89,9 +90,9 @@ For each container you want to use on the deck, you need to load it into your fi
 
 **containers.load** (*container, slot, name*)
 
-	* **container -** type of container (trough-12-row, etc)
-	* **slot -** the slot location on the deck (A1-E3)
-	* **name -** custom name
+	* **container -** type of container (aka "trough-12row")
+	* **slot -** the slot location on the deck ("A1" through "E3")
+	* **name -** custom name, used inside API when saving calibration data
 
 The example below declares 3 different containers and assigns them to the appropriate slots on the deck.
 
@@ -144,7 +145,7 @@ Pipettes
 	* **tip_racks -** array (list) of container(s) where you want to pick up tips
 	* **channels -** number of channels (1 or 8)
 
-This example loads a single channel, 20-200 uL pipette on the b axis that pulls tips from tiprack and deposits them in trash
+This example loads a single channel, 20-200 uL pipette on the ``b`` axis that pulls tips from tiprack and deposits them in trash
 
 .. testcode:: main
 
@@ -340,9 +341,9 @@ Containers are calibrated to the bottom of the well, and each labware definition
 
 .. testcode:: main
 
-	p200.dispense(plate['A1'].top())
-	p200.mix(3, 100, plate['B2'].bottom(5))
-	p200.dispense(plate['A1'].top(-3))
+	p200.dispense(plate['A1'].top())         # at the top of well
+	p200.mix(3, 100, plate['B2'].bottom(5))  # 5mm above bottom of well
+	p200.dispense(plate['A1'].top(-3))       # 3mm below top of well
 
 Homing
 ------
@@ -354,13 +355,14 @@ You can instruct the robot to home at any point in the protocol, or just home on
 	* **axes -** the axes you want to home
 	* **enqueue -** True or False
 
-When the python file is loaded into the protocol, it runs through all of the commands.  When enqueue=False, this will cause the robot to home immediately upon loading the protocol, whereas if enqueue=True, it will run when it is called in the protocol.
+When the python file is loaded into the protocol, it runs through all of the commands.  When enqueue=False (default), this will cause the robot to home immediately upon loading the protocol, whereas if enqueue=True, it will run when it is called in the protocol.
 
 .. testcode:: main
 
-  robot.home(enqueue=True)          
-  robot.home('ab', enqueue=True)
-  robot.home('xyz', enqueue=True)
+  robot.home()                     # causes robot to home immediately
+  robot.home(enqueue=True)         # adds "home" command to protocol queue     
+  robot.home('ab', enqueue=True)   # adds "home ab" command to protocol queue
+  robot.home('xyz', enqueue=True)  # adds "home xyz" command to protocol queue
 
 Move To
 -------

docs/source/module.rst

@@ -20,7 +20,7 @@ Just like a pipette, you need to set up and name your module.
 
 **instruments.Magbead** (*mofset, name*)
 
-	* **mofset -** default to =0
+	* **mosfet -** integer 0-5 (defaults to 0)
 	* **name -** the name you want to call your module
 
 .. testsetup:: main
@@ -31,23 +31,20 @@ Just like a pipette, you need to set up and name your module.
 
 .. testcode:: main
 
-	mag_deck = instruments.Magbead(
-		mosfet=0, 
-		name='mag_deck'
-	)
+	mag_deck = instruments.Magbead(name='mag_deck')
 
 Activate and Deactivate Magnets 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To activate the magnets, use the following command
+To activate the magnets and raise the module's platform, run ``.engage()``:
 
 **module.engage** ()
 
 .. testcode:: main
 
 	mag_deck.engage()
 
-To deactive the magnets, use the following command
+To deactivate the magnets and lower the module's platform, run ``.disengage()``:
 
 **module.disengage** ()
 
@@ -58,7 +55,7 @@ To deactive the magnets, use the following command
 Chain Other Commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Just like aspirate() and dispense() can be chained, you can chain engage() and disengage(), as well as the delay() if you don't want to do anything between engaging and disengaging the magnets.
+Just like ``aspirate()`` and ``dispense()`` can be chained, you can chain ``engage()`` and ``disengage()``, as well as the ``delay()`` if you don't want to do anything between engaging and disengaging the magnets.
 
 .. testcode:: main
 
@@ -68,7 +65,7 @@ Just like aspirate() and dispense() can be chained, you can chain engage() and d
 
 	mag_deck.engage().delay(60).disengage()
 
-You can call delay() with a pipette or a mag_deck module.
+You can call ``delay()`` with a ``Pipette`` or a ``Magbead`` module.
 
 .. testcode:: main
 

docs/source/tips_and_tricks.rst

@@ -7,43 +7,27 @@ The following examples assume the containers and pipettes:
 
 .. testsetup:: tips_main
 
-  from opentrons import Robot
+  from opentrons import robot
   from opentrons import containers, instruments
-  robot = Robot()
-  robot.reset()
   robot.connect('Virtual Smoothie')
 
-  tiprack = containers.load('tiprack-200ul', 'A1')
-  plate = containers.load('96-flat', 'B1')
-  trough = containers.load('trough-12row', 'C1')
-  trash = containers.load('point', 'C2')
+  tiprack = containers.load('tiprack-200ul', 'A1', 'tiprack-for-doctest')
+  plate = containers.load('96-flat', 'B1', 'plate-for-doctest')
+  trough = containers.load('trough-12row', 'C1', 'trough-for-doctest')
+  trash = containers.load('point', 'C2', 'trash-for-doctest')
 
   p200 = instruments.Pipette(axis="b", max_volume=200)
 
 .. testsetup:: tips_demo
 
-  from opentrons import Robot
-  Robot().reset()
-
-.. testcleanup:: tips_main
-  
-  from opentrons.util import singleton
-  from opentrons import Robot
-  del singleton.Singleton._instances[Robot]
-
-.. testcleanup:: tips_demo
-  
-  from opentrons.util import singleton
-  from opentrons import Robot
-  del singleton.Singleton._instances[Robot]
+  from opentrons import robot
+  robot.reset()
 
 .. testcode:: tips_demo
 
-  from opentrons import Robot
+  from opentrons import robot
   from opentrons import containers, instruments
 
-  robot = Robot()
-
   tiprack = containers.load('tiprack-200ul', 'A1')
   plate = containers.load('96-flat', 'B1')
   trough = containers.load('trough-12row', 'C1')

docs/source/updating_firmware.rst

@@ -20,8 +20,6 @@ After downloading, unpack the zip file to view its contents.
 Open the Smoothie's Drive
 ---------------------------------
 
-.. image:: img/update-firmware/driveIcon.png
-
 Power on and plug in your Opentrons liquid handler, and make sure you do not have the app open. You will notice the Smoothieboard shows up on the computer as a Mass Storage Device, like an external hard drive or flash drive.
 
 .. image:: img/update-firmware/firmware_files.png

docs/source/well_access.rst

@@ -20,7 +20,7 @@ Accessing Wells
 Coordinates
 ^^^^^^^^^^^
 
-Wells can be called via their string ['A1'], or their well number [0].  In python, number ranges start with 0, and end at **ask katie for better python description**
+Wells can be called via their string ['A1'], or their well number [0].  List indices in Python start with 0, so for a 96 well plate, the first well is at index 0 and last is at index 95. 
 
 .. code-block:: python
 
@@ -29,7 +29,7 @@ Wells can be called via their string ['A1'], or their well number [0].  In pytho
   plate[94] # G12
   plate[95] # H12
 
-You can also split the coordinates for the rows and columns and use either .rows or .cols.
+You can also split the coordinates for the rows and columns and use either ``.rows`` or ``.cols``.
 
 .. testsetup:: main
 
@@ -94,7 +94,7 @@ Similar to .rows, except .cols.
 Iterating Wells
 -------------------------------
 
-There are many wells to iterate through a plate, well by well, row by row, col by col, or skipping around.  We will show you examples of how to do all of these.
+There are many ways to iterate through a plate, well by well, row by row, col by col, or skipping around.  We will show you examples of how to do all of these.
 
 .. tip::
 
@@ -144,7 +144,7 @@ Other Examples
 Odds & Evens
 ^^^^^^^^^^^^
 
-In order to access every other row, you can utilize the third parameter in range and add a step count to your loop.  A step of 2 skips every other number, giving you all the odds or all the evens (see below) depending on the start of your range.
+In order to access every other row, you can utilize the third parameter in ``range()`` and add a step-count to your loop.  A step-count of ``2`` will skip every other number, so calling ``range(0, 10, 2)`` will create ``[0, 2, 4, 6, 8]``.
 
 .. testcode:: main
 
@@ -164,13 +164,12 @@ Chaining
 ^^^^^^^^
 
 Skipping around multiple chains is easy, once you have the right tools.  There are some python functions that are not inherent to the API, but that can be imported to make your life easier.  You can import the chain function when you import the opentrons API at the start of your python notebook.
-**ask katie for python import explanation**
 
 .. testcode:: main
 
   from itertools import chain
 
-The chain functinos allows you to link two sets of locations together, in this case, two different columns.  The loop will iterate through all wells in column A and column E, while skipping columns BCDFGH.
+The chain function allows you to link two sets of locations together, in this case, two different columns.  The loop will iterate through all wells in column A and column E, while skipping columns BCDFGH.
 
 .. testcode:: main