docs(api): remove creating a new liquid class in 8.5 (#18916)

emilyburghardt · web-flow · commit 8e796af57c48 · 2025-07-16T17:19:08.000-04:00
# Overview  based on conversations around an 8.5 bug, this PR removes mention of customizing a liquid class in 8.5 in the liquid classes, liquid class definitions, and complex commands articles. For now, it leaves `define_liquid_class` visible in the API reference. ## Test Plan and Hands on Testing  sandbox: http://sandbox.docs.opentrons.com/docs-hotfix-new-liquid-class/v2/ ## Changelog  ## Review requests If I align the dictionary example on the left with the other code examples in the doc, the last bracket to properly close the dictionary throws an error (ends the code block early and prevents the docs from building). This is one of Sanniti's dictionary examples, checked with a black formatter and passed simulation. I did space it further _in_ to get the docs to build.  ## Risk assessment  low. I should have gotten every mention of it.
diff --git a/api/docs/v2/complex_commands/parameters.rst b/api/docs/v2/complex_commands/parameters.rst
@@ -94,7 +94,6 @@ If this poses a contamination risk, you can work around it in a few ways:
 
     * Use ``transfer()`` or ``transfer_with_liquid_class()`` with ``new_tip="always"`` instead.
     * Set :py:obj:`.well_bottom_clearance` high enough that the tip doesn't contact liquid in the destination well.
-    * :ref:`Customize your liquid class <customizing-liquid-classes>` to change dispense heights or add touch tip behavior.
     * Use :ref:`building block commands <v2-atomic-commands>` instead of complex commands.
 
 
diff --git a/api/docs/v2/liquid_class_definitions.rst b/api/docs/v2/liquid_class_definitions.rst
@@ -8,13 +8,7 @@ Liquid Class Definitions
 
 A *liquid class definition* specifies nearly all transfer behavior a Flex pipette will perform during a :py:meth:`.InstrumentContext.transfer_with_liquid_class`, :py:meth:`.InstrumentContext.distribute_with_liquid_class`, or :py:meth:`.InstrumentContext.consolidate_with_liquid_class`. Properties, like aspirate flow rate, submerge speed, or dispense position, are required in every liquid class definition. 
 
-This section details specific changes to transfer behavior for each Opentrons-verified liquid class. The transfer steps are listed in the order the robot performs them. Advanced settings like mix, pre-wet tip, touch tip, and blowout are automatically disabled in Opentrons-verified liquid class definitions. 
-
-.. note:: 
-    You can customize a liquid class definition for your workflow, either by customizing individual properties of an Opentrons-verified liquid class definition or creating your own definition from scratch. 
-  
-  For more information, see :ref:`customizing-liquid-classes`. 
-
+This section details specific changes to transfer behavior for each Opentrons-verified liquid class. The transfer steps are listed in the order the robot performs them. Advanced settings like mix, pre-wet tip, touch tip, and blowout are automatically disabled in Opentrons-verified liquid class definitions.
 
 To use the tables below, select your liquid class: :ref:`aqueous`, :ref:`viscous`, or :ref:`volatile`. Then, click different tabs to view your pipette and tip combination. 
 
diff --git a/api/docs/v2/liquid_classes.rst b/api/docs/v2/liquid_classes.rst
@@ -8,7 +8,7 @@ Liquid Classes
 
 Accounting for properties of liquids in your protocol can increase pipetting accuracy on the Flex. For example, a slower flow rate can improve pipetting for a viscous liquid, and an air gap can prevent a volatile liquid from dripping onto the deck. 
 
-This page covers the properties of Opentrons-verified liquid classes, how to use a verified liquid class in your protocol, and how to customize a liquid class. 
+This page covers the properties of Opentrons-verified liquid classes and how to use them in your protocols. 
 
 
 .. _opentrons-verified-liquid-classes: 
@@ -212,78 +212,4 @@ In many cases, the liquid class definition represents fine-tuned changes optimiz
 
 Not all transfer behavior is easily visible. See :ref:`liquid-class-definitions` for a full list of changes based on liquid class, pipette, and tip combination. For more detail on individual transfer settings, see :ref:`liquid-control`. 
 
-.. _customizing-liquid-classes:
 
-Customizing Liquid Classes
-===========================
-
-You can create your own liquid class to customize transfer behavior for any liquid in a Flex protocol. To make changes, you can edit individual properties of an existing liquid class, or add properties to a new liquid class. 
-
-To customize an Opentrons-verified liquid class, first add your pipettes, tips, trash, and labware. Then, use :py:meth:`~.ProtocolContext.get_liquid_class` to specify the liquid class you'll make changes to::
-
-  # get base liquid class and custom properties for the Flex pipette and tips 
-
-    custom_water = protocol.get_liquid_class(name="water")
-    custom_water_properties=custom_water.get_for(pipette, tiprack)
-
-.. versionadded:: 2.24
-
-Next, edit indivual liquid class properties based on your Flex pipette and tip combination. 
-
-.. code-block:: python
-    
-  # edit aspirate submerge speed to 80 μL/sec
-    custom_water_properties.aspirate.submerge.speed = 80
-
-  # edit aspirate flow rate by volume for 10 μL and 20 μL volumes
-    custom_water_properties.aspirate.flow_rate_by_volume.set_for_volume = [(10.0, 40.0)
-    custom_water_properties.aspirate.flow_rate_by_volume.set_for_volume = [(20.0, 30.0)]
-
-  # edit to delay for 1 sec before retracting after an aspirate
-    custom_water_properties.aspirate.retract.delay.enabled = True
-    custom_water_properties.aspirate.retract.delay.duration = 1.0
-
-.. versionadded:: 2.24
-
-Then, complete your transfers with the modified ``custom_water`` liquid class. 
-
-All Opentrons-verified liquid classes position the pipette relative to the well. To customize your liquid class to use :ref:`meniscus-relative <well-meniscus>` locations, set the ``positionReference`` to ``"liquid-meniscus"`` for actions like an aspirate or dispense.   
-
-
-.. _new-liquid-classes:
-
-Defining New Liquid Classes
-============================
-
-You can also create a new liquid class for your Flex protocols. Instead of using an Opentrons-verified liquid class, you'll start from scratch, providing a value for `every required property <https://github.com/Opentrons/opentrons/blob/edge/shared-data/liquid-class/schemas/1.json>`__ in your liquid class. 
-
-.. code-block:: python
-
- # examples of required properties in a dictionary for the pipette and tip racks
- custom_liquid_class_properties = {
-    "flex_1channel_50": {
-        "opentrons/opentrons_flex_96_tiprack_50ul/1": {
-            "aspirate": {
-                "aspirate_position": {
-                    "offset": {"x": 1, "y": 2, "z": 3},
-                    "position_reference": "well-bottom",
-                },
-            },
-        },
-    },
-  }
-              
- # create a new liquid class
- custom_viscous = protocol.define_liquid_class(
-    name="custom_viscous",
-    properties=custom_liquid_class_properties,
-    display_name="Custom Viscous"
-  )
-
-.. versionadded:: 2.24
-
-The example above is shortened and only includes aspirate position properties. To create your liquid class, you'll need to define values for all `required properties <https://github.com/Opentrons/opentrons/blob/edge/shared-data/liquid-class/schemas/1.json>` in your new liquid class, like submerging before aspirating or after dispensing, speeds and flow rates, and position offsets. 
-
-.. note:: 
-
-    The :py:meth:`.ProtocolContext.get_liquid_class` method only accepts Opentrons-verified liquid classes, like ``glycerol_50``. You'll need to use :py:meth:`.ProtocolContext.define_liquid_class` in each Flex protocol that uses a custom liquid class.
diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst
@@ -147,7 +147,6 @@ Version 2.24
 - Adds the ability to perform liquid handling actions using :ref:`liquid classes <liquid-classes>`.
 
   - :py:meth:`.ProtocolContext.get_liquid_class` accesses :ref:`Opentrons-verified liquid class definitions <liquid-class-definitions>` for aqueous, volatile, and viscous liquids.
-  - :py:meth:`.ProtocolContext.define_liquid_class` lets you create your own liquid classes from verified classes or from scratch.
   - New :py:class:`.InstrumentContext` methods — :py:meth:`.transfer_with_liquid_class`, :py:meth:`.distribute_with_liquid_class`, and :py:meth:`.consolidate_with_liquid_class` — move liquids according to their properties.
 - :py:meth:`.air_gap`, :py:meth:`.blow_out`, :py:meth:`.dispense`, :py:meth:`.mix`, and :py:meth:`.touch_tip` have new parameters for advanced settings that are also available in Protocol Designer.
 
