docs(api): new ProtocolContext.deck behavior for multi-slot modules

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
 ------------

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(

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``.
  """