From f30f52ad5265adb15eda065dd308a3a133e7f2f9 Mon Sep 17 00:00:00 2001
From: Ed Cormany <edward.cormany@opentrons.com>
Date: Wed, 21 Feb 2024 16:45:06 -0500
Subject: [PATCH] docs(api): new `ProtocolContext.deck` behavior for multi-slot
 modules (#14523)

Follow up to dev work in #14491.
---
 api/docs/v2/versioning.rst                      |  9 ---------
 .../protocol_api/instrument_context.py          |  4 ----
 .../opentrons/protocol_api/protocol_context.py  | 17 ++++++++++++++---
 3 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst
index 5d8e4cd3b82..10cd50d7392 100644
--- a/api/docs/v2/versioning.rst
+++ b/api/docs/v2/versioning.rst
@@ -126,11 +126,6 @@ This table lists the correspondence between Protocol API versions and robot soft
 Changes in API Versions
 =======================
 
-Version 2.17
-------------
-
-- :py:meth:`.dispense` will now raise an error if you try to dispense more than is available.
-
 Version 2.16
 ------------
 
@@ -152,10 +147,6 @@ This version introduces new features for Flex and adds and improves methods for
 
   - :py:obj:`.ProtocolContext.fixed_trash` and :py:obj:`.InstrumentContext.trash_container` now return :py:class:`.TrashBin` objects instead of :py:class:`.Labware` objects.
   - Flex will no longer automatically drop tips in the trash at the end of a protocol. You can add a :py:meth:`.drop_tip()` command to your protocol or use the Opentrons App to drop the tips.
-  
-- Known issues
-
-  - It's possible to load a Thermocycler and then load another item in slot A1. Don't do this, as it could lead to unexpected pipetting behavior and crashes.
 
 Version 2.15
 ------------
diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py
index 4403f8e5912..45b7d385684 100644
--- a/api/src/opentrons/protocol_api/instrument_context.py
+++ b/api/src/opentrons/protocol_api/instrument_context.py
@@ -345,10 +345,6 @@ def dispense(  # noqa: C901
 
         .. versionchanged:: 2.15
             Added the ``push_out`` parameter.
-
-        .. versionchanged:: 2.17
-            Now raises an exception if you try to dispense more than is available.
-            Previously, it would silently clamp.
         """
         if self.api_version < APIVersion(2, 15) and push_out:
             raise APIVersionError(
diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py
index e7c6e63de8d..a89c2a04f62 100644
--- a/api/src/opentrons/protocol_api/protocol_context.py
+++ b/api/src/opentrons/protocol_api/protocol_context.py
@@ -1066,9 +1066,17 @@ def deck(self) -> Deck:
         For instance, ``deck[1]``, ``deck["1"]``, and ``deck["D1"]``
         will all return the object loaded in the front-left slot.
 
-        The value will be a :py:obj:`~opentrons.protocol_api.Labware` if the slot contains a
-        labware, a module context if the slot contains a hardware
-        module, or ``None`` if the slot doesn't contain anything.
+        The value for each key depends on what is loaded in the slot:
+          - A :py:obj:`~opentrons.protocol_api.Labware` if the slot contains a labware.
+          - A module context if the slot contains a hardware module.
+          - ``None`` if the slot doesn't contain anything.
+
+        A module that occupies multiple slots is set as the value for all of the
+        relevant slots. Currently, the only multiple-slot module is the Thermocycler.
+        When loaded, the :py:class:`ThermocyclerContext` object is the value for
+        ``deck`` keys ``"A1"`` and ``"B1"`` on Flex, and ``7``, ``8``, ``10``, and
+        ``11`` on OT-2. In API version 2.13 and earlier, only slot 7 keyed to the
+        Thermocycler object, and slots 8, 10, and 11 keyed to ``None``.
 
         Rather than filtering the objects in the deck map yourself,
         you can also use :py:attr:`loaded_labwares` to get a dict of labwares
@@ -1085,6 +1093,9 @@ def deck(self) -> Deck:
             reflect the new deck state, add a :py:meth:`.pause` or use
             :py:meth:`.move_labware` instead.
 
+        .. versionchanged:: 2.14
+           Includes the Thermocycler in all of the slots it occupies.
+
         .. versionchanged:: 2.15
            ``del`` sets the corresponding labware's location to ``OFF_DECK``.
         """