docs(api): new tip overlap in Python API 2.19 (#15404)

# Overview

This updates the Python API documentation to version 2.19. The only
change in this API version is updated tip overlap values for Flex. This
doesn't change the usage of `pick_up_tip()`, but does change its
physical behavior in an API-gated manner.

Addresses RTC-481, RTC-467.

# Test Plan

[Sandbox](http://sandbox.docs.opentrons.com/docs-tip-overlap/v2/)

# Changelog

- Bump version to 2.19 and add notes to Versioning page.
- Add brief description of how tip overlap works, and how to update and
validate protocols, to `pick_up_tip()`API Reference entry.
- Clean up descriptions of picking up and dropping tips on the
Manipulating Pipette Tips page.

# Review requests

Confirm that all new behavior and advice is accurate.

# Risk assessment

None, docs.

api/docs/v2/basic_commands/pipette_tips.rst

@@ -19,20 +19,20 @@ To pick up a tip, call the :py:meth:`~.InstrumentContext.pick_up_tip` method wit
     
     pipette.pick_up_tip()
 
-This simple statement works because the variable ``tiprack_1`` in the sample protocol includes the on-deck location of the tip rack (Flex ``location="D3"``, OT-2 ``location=3``) *and* the ``pipette`` variable includes the argument ``tip_racks=[tiprack_1]``. Given this information, the robot moves to the tip rack and picks up a tip from position A1 in the rack. On subsequent calls to ``pick_up_tip()``, the robot will use the next available tip. For example::
+When added to the protocol template, this simple statement works because the API knows which tip rack is associated with ``pipette``, as indicated by ``tip_racks=[tiprack_1]`` in the :py:meth:`.load_instrument` call. And it knows the on-deck location of the tip rack (slot D3 on Flex, slot 3 on OT-2) from the ``location`` argument of :py:meth:`~.ProtocolContext.load_labware`. Given this information, the robot moves to the tip rack and picks up a tip from position A1 in the rack. On subsequent calls to ``pick_up_tip()``, the robot will use the next available tip. For example::
 
     pipette.pick_up_tip()  # picks up tip from rack location A1
     pipette.drop_tip()     # drops tip in trash bin
     pipette.pick_up_tip()  # picks up tip from rack location B1
     pipette.drop_tip()     # drops tip in trash bin 
 
-If you omit the ``tip_rack`` argument from the ``pipette`` variable, the API will raise an error. You must pass in the tip rack's location to ``pick_up_tip`` like this::
+If you omit the ``tip_rack`` argument from the ``pipette`` variable, the API will raise an error. In that case, you must pass the tip rack's location to ``pick_up_tip`` like this::
     
     pipette.pick_up_tip(tiprack_1["A1"])
     pipette.drop_tip()
     pipette.pick_up_tip(tiprack_1["B1"]) 
 
-If coding the location of each tip seems inefficient or tedious, try using a ``for`` loop to automate a sequential tip pick up process. When using a loop, the API keeps track of tips and manages tip pickup for you. But ``pick_up_tip`` is still a powerful feature. It gives you direct control over tip use when that’s important in your protocol.
+In most cases, it's best to associate tip racks with a pipette and let the API automatically track pickup location for you. This also makes it easy to pick up tips when iterating over a loop, as shown in the next section.
 
 .. versionadded:: 2.0
 
@@ -55,19 +55,19 @@ First, add another tip rack to the sample protocol::
         location="C3"
     )
 
-Next, append the new tip rack to the pipette's ``tip_rack`` property::
+Next, change the pipette's ``tip_rack`` property to include the additional rack::
 
     pipette = protocol.load_instrument(
         instrument_name="flex_1channel_1000",
         mount="left",
         tip_racks=[tiprack_1, tiprack_2],
     )
-    pipette_1.tip_racks.append(tiprack_2)
 
-Finally, sum the tip count in the range::
+Finally, iterate over a larger range::
 
     for i in range(192):
         pipette.pick_up_tip()
+        # liquid handling commands
         pipette.drop_tip()
 
 For a more advanced "real-world" example, review the :ref:`off-deck location protocol <off-deck-location>` on the :ref:`moving-labware` page. This example also uses a ``for`` loop to iterate through a tip rack, but it includes other commands that pause the protocol and let you replace an on-deck tip rack with another rack stored in an off-deck location.
@@ -81,15 +81,24 @@ To drop a tip in the pipette's trash container, call the :py:meth:`~.InstrumentC
     
     pipette.pick_up_tip()
 
-You can also specify where to drop the tip by passing in a location. For example, this code drops a tip in the trash bin and returns another tip to to a previously used well in a tip rack::
+You can specify where to drop the tip by passing in a location. For example, this code drops a tip in the trash bin and returns another tip to to a previously used well in a tip rack::
 
     pipette.pick_up_tip()            # picks up tip from rack location A1
-    pipette.drop_tip()               # drops tip in trash bin 
+    pipette.drop_tip()               # drops tip in default trash container
     pipette.pick_up_tip()            # picks up tip from rack location B1
     pipette.drop_tip(tiprack["A1"])  # drops tip in rack location A1
 
 .. versionadded:: 2.0
 
+Another use of the ``location`` parameter is to drop a tip in a specific trash container. For example, calling ``pipette.drop_tip(chute)`` will dispose tips in the waste chute, even if the pipette's default trash container is a trash bin::
+
+    pipette.pick_up_tip()    # picks up tip from rack location A1
+    pipette.drop_tip()       # drops tip in default trash container
+    pipette.pick_up_tip()    # picks up tip from rack location B1
+    pipette.drop_tip(chute)  # drops tip in waste chute
+
+.. versionadded:: 2.16
+
 .. _pipette-return-tip:
 
 Returning a Tip

api/docs/v2/conf.py

@@ -99,7 +99,7 @@
 # use rst_prolog to hold the subsitution
 # update the apiLevel value whenever a new minor version is released
 rst_prolog = f"""
-.. |apiLevel| replace:: 2.18
+.. |apiLevel| replace:: 2.19
 .. |release| replace:: {release}
 """
 

api/docs/v2/versioning.rst

@@ -84,6 +84,8 @@ This table lists the correspondence between Protocol API versions and robot soft
 +-------------+------------------------------+
 | API Version | Introduced in Robot Software |
 +=============+==============================+
+|     2.19    |          7.3.1               |
++-------------+------------------------------+
 |     2.18    |          7.3.0               |
 +-------------+------------------------------+
 |     2.17    |          7.2.0               |
@@ -130,6 +132,13 @@ This table lists the correspondence between Protocol API versions and robot soft
 Changes in API Versions
 =======================
 
+Version 2.19
+------------
+
+Opentrons recommends updating protocols from ``apiLevel`` 2.18 to 2.19 to take advantage of improved pipetting behavior.
+
+- This version uses new values for how much a tip overlaps with the pipette nozzle when the pipette picks up tips. This can correct errors caused by the robot positioning the tip slightly lower than intended, potentially making contact with labware. See :py:meth:`.pick_up_tip` for additional details.
+
 Version 2.18
 ------------
 

api/src/opentrons/protocol_api/instrument_context.py

@@ -803,6 +803,21 @@ def pick_up_tip(  # noqa: C901
         :py:meth:`.Labware.wells`. To adjust where the sequence starts, use
         :py:obj:`.starting_tip`.
 
+        The exact position for tip pickup accounts for the length of the tip and how
+        much the tip overlaps with the pipette nozzle. These measurements are fixed
+        values on Flex, and are based on the results of tip length calibration on OT-2.
+
+        .. note::
+            API version 2.19 updates the tip overlap values for Flex. When updating a
+            protocol from 2.18 (or lower) to 2.19 (or higher), pipette performance
+            should improve without additional changes to your protocol. Nevertheless, it
+            is good practice after updating to do the following:
+
+            - Run Labware Position Check.
+            - Perform a dry run of your protocol.
+            - If tip position is slightly higher than expected, adjust the ``location``
+              parameter of pipetting actions to achieve the desired result.
+
         :param location: The location from which to pick up a tip. The ``location``
                          argument can be specified in several ways:
 
@@ -865,6 +880,9 @@ def pick_up_tip(  # noqa: C901
             instead always prepare during :py:meth:`.aspirate`. Version 2.12 and earlier
             will raise an ``APIVersionError`` if a value is set for ``prep_after``.
 
+        .. versionchanged:: 2.19
+            Uses new values for how much a tip overlaps with the pipette nozzle.
+
         :returns: This instance.
         """