From 76bf6b8e7d442230ff1a7382683e153b9da93dfd Mon Sep 17 00:00:00 2001
From: Ed Cormany <edward.cormany@opentrons.com>
Date: Wed, 13 Dec 2023 16:02:45 -0500
Subject: [PATCH] docs(api): new section for `push_out` (#14183)

---
 api/docs/v2/basic_commands/liquids.rst        | 21 +++++++++++++++++--
 .../protocol_api/instrument_context.py        |  5 +++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst
index 00e81449a40..f703acb8884 100644
--- a/api/docs/v2/basic_commands/liquids.rst
+++ b/api/docs/v2/basic_commands/liquids.rst
@@ -111,10 +111,27 @@ Flex and OT-2 pipettes dispense at :ref:`default flow rates <new-plunger-flow-ra
 
     pipette.dispense(200, plate['B1'], rate=2.0)
 
-.. Removing the 2 notes here from the original. Covered by new revisions.
-
 .. versionadded:: 2.0
 
+.. _push-out-dispense:
+
+Push Out After Dispense
+-----------------------
+
+The optional ``push_out`` parameter of ``dispense()`` helps ensure all liquid leaves the tip. Use ``push_out`` for applications that require moving the pipette plunger lower than the default, without performing a full :ref:`blow out <blow-out>`.
+
+For example, this dispense action moves the plunger the equivalent of an additional 5 µL beyond where it would stop if ``push_out`` was set to zero or omitted::
+
+    pipette.pick_up_tip()
+    pipette.aspirate(100, plate['A1'])
+    pipette.dispense(100, plate['B1'], push_out=5)
+    pipette.drop_tip()
+
+.. versionadded:: 2.15
+
+.. note::
+    In version 7.0.2 and earlier of the robot software, you could accomplish a similar result by dispensing a volume greater than what was aspirated into the pipette. In version 7.1.0 and later, the API will return an error. Calculate the difference between the two amounts and use that as the value of ``push_out``.
+
 .. _new-blow-out:
 
 .. _blow-out:
diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py
index 824f7de9160..29a8114e364 100644
--- a/api/src/opentrons/protocol_api/instrument_context.py
+++ b/api/src/opentrons/protocol_api/instrument_context.py
@@ -330,6 +330,8 @@ def dispense(
         :type rate: float
         :param push_out: Continue past the plunger bottom to help ensure all liquid
                          leaves the tip. Measured in µL. The default value is ``None``.
+
+                         See :ref:`push-out-dispense` for details.
         :type push_out: float
 
         :returns: This instance.
@@ -341,6 +343,9 @@ def dispense(
             ``location``, specify it as a keyword argument:
             ``pipette.dispense(location=plate['A1'])``.
 
+        .. versionchanged:: 2.15
+            Added the ``push_out`` parameter.
+
         """
         if self.api_version < APIVersion(2, 15) and push_out:
             raise APIVersionError(