diff --git a/api/Makefile b/api/Makefile index c6e78d04939..81d49ea5a83 100755 --- a/api/Makefile +++ b/api/Makefile @@ -130,14 +130,11 @@ format: $(python) -m black src tests setup.py docs/build/html/v%: docs/v% - $(sphinx_build_allow_warnings) -b html -d docs/build/doctrees -n $< $@ -# sphinx wont automatically do this because it's only in a template - $(SHX) cp docs/img/lightbulb.jpg $@/_images/ + $(sphinx_build) -b html -d docs/build/doctrees -n $< $@ docs/build/html/hardware: docs/hardware src/opentrons/hardware_control $(sphinx_build_allow_warnings) -b html -d docs/build/doctrees -n $< $@ $(SHX) mkdir $@/_images/ - $(SHX) cp docs/img/lightbulb.jpg $@/_images/ docs/dist/v%: docs/build/html/v% $(SHX) mkdir -p $@ diff --git a/api/docs/img/lightbulb.jpg b/api/docs/img/lightbulb.jpg deleted file mode 100644 index 41f67329264..00000000000 Binary files a/api/docs/img/lightbulb.jpg and /dev/null differ diff --git a/api/docs/v2/complex_commands/sources_destinations.rst b/api/docs/v2/complex_commands/sources_destinations.rst index 908dfbff875..3c8e725a9aa 100644 --- a/api/docs/v2/complex_commands/sources_destinations.rst +++ b/api/docs/v2/complex_commands/sources_destinations.rst @@ -103,7 +103,7 @@ Aspirating and Dispensing See :ref:`complex-tip-refilling` below for cases where the total amount to be dispensed is greater than the capacity of the tip. .. figure:: ../../img/complex_commands/robot_distribute.png - :name: Transfer + :name: Distribute :scale: 35% :align: center @@ -120,7 +120,7 @@ See :ref:`complex-tip-refilling` below for cases where the total amount to be di See :ref:`complex-tip-refilling` below for cases where the total amount to be aspirated is greater than the capacity of the tip. .. figure:: ../../img/complex_commands/robot_consolidate.png - :name: Transfer + :name: Consolidate :scale: 35% :align: center diff --git a/api/docs/v2/conf.py b/api/docs/v2/conf.py index e3c68989a46..985c9b403af 100644 --- a/api/docs/v2/conf.py +++ b/api/docs/v2/conf.py @@ -424,3 +424,26 @@ # -- Options for tabs ----------------------------------------------------- sphinx_tabs_disable_tab_closing = True + +# -- Suppress autodoc warnings -------------------------------------------- + +# Ignore warnings for deliberately missing/undocumented things that appear +# in automatically generated type signatures. +# +# The goal here is to pass through any warnings for bad targets of MANUALLY +# created links. +nitpick_ignore_regex = [ + ("py:class", r".*Optional\[.*"), # any Optional with bad members + ("py:class", r".*commands\.types.*"), + ("py:class", r".*hardware_control.*"), + ("py:class", r".*legacy_broker.*"), + ("py:class", r".*protocol_api\.core.*"), + ("py:class", r".*api_support.*"), + ("py:class", r".*duration\.estimator.*"), + ("py:class", r".*protocols\.types.*"), + ("py:class", r".*protocol_api\.deck.*"), + ("py:class", r".*protocol_api\.config.*"), + ("py:class", r".*opentrons_shared_data.*"), + ("py:class", r".*types\.DeckSlotName.*"), # TODO: RTC-386 + ("py:class", r'.*AbstractLabware|APIVersion|LabwareLike|LoadedCoreMap|ModuleTypes|NoneType|OffDeckType|ProtocolCore|WellCore'), # laundry list of not fully qualified things +] diff --git a/api/docs/v2/deck_slots.rst b/api/docs/v2/deck_slots.rst index 0088c0a4aee..2c38e70755f 100644 --- a/api/docs/v2/deck_slots.rst +++ b/api/docs/v2/deck_slots.rst @@ -110,7 +110,7 @@ Which fixtures you need to configure depend on both load methods and the effects Staging Area Slots ------------------ -Slots A4 through D4 are the staging area slots. Pipettes can't reach the staging area, but these slots are always available in the API for loading and moving labware. Using a slot in column 4 as the ``location`` argument of :py:meth:`.load_labware` or the ``new_location`` argument of :py:meth:`.move_labware` will require the corresponding staging area slot in the robot's deck configuration:: +Slots A4 through D4 are the staging area slots. Pipettes can't reach the staging area, but these slots are always available in the API for loading and moving labware. Using a slot in column 4 as the ``location`` argument of :py:meth:`~.ProtocolContext.load_labware` or the ``new_location`` argument of :py:meth:`.move_labware` will require the corresponding staging area slot in the robot's deck configuration:: plate_1 = protocol.load_labware( load_name="corning_96_wellplate_360ul_flat", location="C3" @@ -150,7 +150,7 @@ Starting in API version 2.16, you must load trash bin fixtures in your protocol .. versionadded:: 2.16 .. note:: - The :py:class:`TrashBin` class doesn't have any callable methods, so you don't have to save the result of ``load_trash_bin()`` to a variable, especially if your protocol only loads a single trash container. Being able to reference the trash bin by name is useful when dealing with multiple trash containers. + The :py:class:`.TrashBin` class doesn't have any callable methods, so you don't have to save the result of ``load_trash_bin()`` to a variable, especially if your protocol only loads a single trash container. Being able to reference the trash bin by name is useful when dealing with multiple trash containers. Call ``load_trash_bin()`` multiple times to add more than one bin. See :ref:`pipette-trash-containers` for more information on using pipettes with multiple trash bins. @@ -169,7 +169,7 @@ To use the waste chute, first use :py:meth:`.load_waste_chute` to load it in slo The ``load_waste_chute()`` method takes no arguments, since D3 is the only valid location for the chute. However, there are multiple variant configurations of the waste chute, depending on how other methods in your protocol use it. -The waste chute is installed either on a standard deck plate adapter or on a deck plate adapter with a staging area. If any :py:meth:`.load_labware` or :py:meth:`.move_labware` calls in your protocol reference slot D4, you have to use the deck plate adapter with staging area. +The waste chute is installed either on a standard deck plate adapter or on a deck plate adapter with a staging area. If any :py:meth:`~.ProtocolContext.load_labware` or :py:meth:`.move_labware` calls in your protocol reference slot D4, you have to use the deck plate adapter with staging area. The waste chute has a removable cover with a narrow opening which helps prevent aerosols and droplets from contaminating the working area. 1- and 8-channel pipettes can dispense liquid, blow out, or drop tips through the opening in the cover. Any of the following require you to remove the cover. diff --git a/api/docs/v2/index.rst b/api/docs/v2/index.rst index 0520353fca3..92b770e4065 100644 --- a/api/docs/v2/index.rst +++ b/api/docs/v2/index.rst @@ -36,7 +36,7 @@ Getting Started If you want to **dive right into code**, take a look at our :ref:`new-examples` and the comprehensive :ref:`protocol-api-reference`. -When you're ready to **try out a protocol**, download the `Opentrons App `_, import the protocol file, and run it on your robot. +When you're ready to **try out a protocol**, download the `Opentrons App `__, import the protocol file, and run it on your robot. .. _overview-section-v2: @@ -170,7 +170,7 @@ More Resources Opentrons App +++++++++++++ -The `Opentrons App `_ is the easiest way to run your Python protocols. The app `supports `_ the latest versions of macOS, Windows, and Ubuntu. +The `Opentrons App `__ is the easiest way to run your Python protocols. The app `supports `_ the latest versions of macOS, Windows, and Ubuntu. Support +++++++ diff --git a/api/docs/v2/moving_labware.rst b/api/docs/v2/moving_labware.rst index a0780116c14..0d0fbc3385f 100644 --- a/api/docs/v2/moving_labware.rst +++ b/api/docs/v2/moving_labware.rst @@ -132,7 +132,7 @@ If the labware is inaccessible, the API will raise an error. Movement into the Waste Chute ============================= -Move used tip racks and well plates to the waste chute to dispose of them. This requires you to first :ref:`configure the waste chute ` in your protocol. Then use the loaded :py:class:`WasteChute` object as the value of ``new_location``:: +Move used tip racks and well plates to the waste chute to dispose of them. This requires you to first :ref:`configure the waste chute ` in your protocol. Then use the loaded :py:class:`.WasteChute` object as the value of ``new_location``:: chute = protocol.load_waste_chute() protocol.move_labware( diff --git a/api/docs/v2/new_advanced_running.rst b/api/docs/v2/new_advanced_running.rst index b528e5ff22d..5a867c0d172 100644 --- a/api/docs/v2/new_advanced_running.rst +++ b/api/docs/v2/new_advanced_running.rst @@ -145,6 +145,7 @@ Command Line ------------ .. TODO update with separate links to OT-2 and Flex setup, when new Flex process is in manual or on help site + The robot's command line is accessible either by going to **New > Terminal** in Jupyter or `via SSH `_. To execute a protocol from the robot's command line, copy the protocol file to the robot with ``scp`` and then run the protocol with ``opentrons_execute``: diff --git a/api/docs/v2/new_protocol_api.rst b/api/docs/v2/new_protocol_api.rst index c54434eca8e..aad1d46b83d 100644 --- a/api/docs/v2/new_protocol_api.rst +++ b/api/docs/v2/new_protocol_api.rst @@ -30,6 +30,11 @@ Labware :members: :exclude-members: next_tip, use_tips, previous_tip, return_tips +.. autoclass:: opentrons.protocol_api.TrashBin + +.. autoclass:: opentrons.protocol_api.WasteChute + + Wells and Liquids ================= .. autoclass:: opentrons.protocol_api.Well diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index 8efa72080b0..7b1bb805824 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -180,7 +180,7 @@ First, tip tracking is not available with column 1. You must always specify a `` pipette.pick_up_tip(row_a.pop()) # pick up A11-H11 pipette.drop_tip() -This code first constructs a list of all the wells in row A of the tip rack. Then, when picking up a tip, instead of referencing one of those wells directly, the ``location`` is set to ``row_a.pop()``. This uses the built-in :py:meth:`pop` method to get the last item from the list and remove it from the list. If you keep using this approach to pick up tips, you'll get an error once the tip rack is empty — not from the API, but from Python itself, since you're trying to ``pop`` an item from an empty list. +This code first constructs a list of all the wells in row A of the tip rack. Then, when picking up a tip, instead of referencing one of those wells directly, the ``location`` is set to ``row_a.pop()``. This uses the `built-in pop method `_ to get the last item from the list and remove it from the list. If you keep using this approach to pick up tips, you'll get an error once the tip rack is empty — not from the API, but from Python itself, since you're trying to ``pop`` an item from an empty list. Second, the API does not provide the same collision detection for the column 1 layout that it does for column 12. diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst index f8ff405221c..2fabc14908c 100644 --- a/api/docs/v2/versioning.rst +++ b/api/docs/v2/versioning.rst @@ -182,13 +182,13 @@ This version introduces support for the Opentrons Flex robot, instruments, modul - Use coordinates or numbers to specify :ref:`deck slots `. These formats match physical labels on Flex and OT-2, but you can use either system, regardless of ``robotType``. - - The new :py:meth:`.load_adapter` method lets you load adapters and labware separately on modules, and lets you load adapters directly in deck slots. See :ref:`labware-on-adapters`. + - The new module context ``load_adapter()`` methods let you load adapters and labware separately on modules, and :py:meth:`.ProtocolContext.load_adapter` lets you load adapters directly in deck slots. See :ref:`labware-on-adapters`. - Move labware manually using :py:meth:`.move_labware`, without having to stop your protocol. - Manual labware moves support moving to or from the new :py:obj:`~.protocol_api.OFF_DECK` location (outside of the robot). - - :py:meth:`.load_labware` also accepts :py:obj:`~.protocol_api.OFF_DECK` as a location. This lets you prepare labware to be moved onto the deck later in a protocol. + - :py:meth:`.ProtocolContext.load_labware` also accepts :py:obj:`~.protocol_api.OFF_DECK` as a location. This lets you prepare labware to be moved onto the deck later in a protocol. - The new ``push_out`` parameter of the :py:meth:`.dispense` method helps ensure that the pipette dispenses all of its liquid when working with very small volumes. @@ -244,10 +244,10 @@ If you specify an API version of ``2.13`` or lower, your protocols will continue because the plunger's speed is a stepwise function of the volume. Use :py:attr:`.InstrumentContext.flow_rate` to set the flow rate in µL/s, instead. - - ``ModuleContext.load_labware_object`` was removed as an unnecessary internal method. + - ``load_labware_object()`` was removed from module contexts as an unnecessary internal method. - - ``ModuleContext.geometry`` was removed in favor of - :py:attr:`.ModuleContext.model` and :py:attr:`.ModuleContext.type` + - ``geometry`` was removed from module contexts in favor of + ``model`` and ``type`` attributes. - ``Well.geometry`` was removed as unnecessary. @@ -337,7 +337,7 @@ Version 2.8 Version 2.7 ----------- -- Added :py:meth:`.InstrumentContext.pair_with`, an experimental feature for moving both pipettes simultaneously. +- Added ``InstrumentContext.pair_with()``, an experimental feature for moving both pipettes simultaneously. .. note:: diff --git a/api/src/opentrons/protocol_api/_trash_bin.py b/api/src/opentrons/protocol_api/_trash_bin.py index 90636343936..aaaf46e40f4 100644 --- a/api/src/opentrons/protocol_api/_trash_bin.py +++ b/api/src/opentrons/protocol_api/_trash_bin.py @@ -4,7 +4,7 @@ class TrashBin: """Represents a Flex trash bin. - See :py:obj:`ProtocolContext.load_trash_bin`. + See :py:meth:`.ProtocolContext.load_trash_bin`. """ def __init__(self, location: DeckSlotName, addressable_area_name: str) -> None: diff --git a/api/src/opentrons/protocol_api/_waste_chute.py b/api/src/opentrons/protocol_api/_waste_chute.py index 8af8cafe445..8e7ab765151 100644 --- a/api/src/opentrons/protocol_api/_waste_chute.py +++ b/api/src/opentrons/protocol_api/_waste_chute.py @@ -1,5 +1,5 @@ class WasteChute: """Represents a Flex waste chute. - See :py:obj:`ProtocolContext.load_waste_chute`. + See :py:meth:`.ProtocolContext.load_waste_chute`. """ diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 37c1ea795eb..8712367671e 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -980,10 +980,10 @@ def drop_tip( unusually large height above the tip rack, you could call ``pipette.drop_tip(tip_rack["A1"].top(z=10))``. - As a :py:class:`.TrashBin`. This uses a default location relative to the - TrashBin object. For example, + ``TrashBin`` object. For example, ``pipette.drop_tip(location=trash_bin)``. - As a :py:class:`.WasteChute`. This uses a default location relative to - the WasteChute object. For example, + the ``WasteChute`` object. For example, ``pipette.drop_tip(location=waste_chute)``. :param location: @@ -1543,7 +1543,7 @@ def trash_container(self) -> Union[labware.Labware, TrashBin, WasteChute]: This is the property used to determine where to drop tips and blow out liquids when calling :py:meth:`drop_tip` or :py:meth:`blow_out` without arguments. - You can set this to a :py:obj:`Labware`, :py:obj:`TrashBin`, or :py:obj:`WasteChute`. + You can set this to a :py:obj:`Labware`, :py:class:`.TrashBin`, or :py:class:`.WasteChute`. The default value depends on the robot type and API version: diff --git a/api/src/opentrons/protocol_api/labware.py b/api/src/opentrons/protocol_api/labware.py index e774cb2a6f8..f0338d062af 100644 --- a/api/src/opentrons/protocol_api/labware.py +++ b/api/src/opentrons/protocol_api/labware.py @@ -393,17 +393,17 @@ def parent(self) -> Union[str, Labware, ModuleTypes, OffDeckType]: If the labware is directly on the robot's deck, the ``str`` name of the deck slot, like ``"D1"`` (Flex) or ``"1"`` (OT-2). See :ref:`deck-slots`. - If the labware is on a module, a :py:class:`ModuleContext`. + If the labware is on a module, a module context. If the labware is on a labware or adapter, a :py:class:`Labware`. If the labware is off-deck, :py:obj:`OFF_DECK`. .. versionchanged:: 2.14 - Return type for module parent changed to :py:class:`ModuleContext`. - Prior to this version, an internal geometry interface is returned. + Return type for module parent changed. + Prior to this version, an internal geometry interface was returned. .. versionchanged:: 2.15 - Will return a :py:class:`Labware` if the labware was loaded onto a labware/adapter. + Will return a :py:class:`Labware` if the labware is loaded onto a labware/adapter. Will now return :py:obj:`OFF_DECK` if the labware is off-deck. Formerly, if the labware was removed by using ``del`` on :py:obj:`.deck`, this would return where it was before its removal. diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index 4d520ea4f54..76ae81ad38e 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -1029,7 +1029,7 @@ def deck(self) -> Deck: will all return the object loaded in the front-left slot. (See :ref:`deck-slots`.) The value will be a :py:obj:`~opentrons.protocol_api.Labware` if the slot contains a - labware, a :py:obj:`~opentrons.protocol_api.ModuleContext` if the slot contains a hardware + labware, a module context if the slot contains a hardware module, or ``None`` if the slot doesn't contain anything. Rather than filtering the objects in the deck map yourself, @@ -1064,7 +1064,7 @@ def fixed_trash(self) -> Union[Labware, TrashBin]: In API version 2.16 and later, the fixed trash only exists in OT-2 protocols. It is a :py:class:`.TrashBin` object, which doesn't have any wells. Trying to access ``fixed_trash`` in a Flex protocol will raise an error. See :ref:`configure-trash-bin` for details on using the movable trash in Flex protocols. .. versionchanged:: 2.16 - Returns a :py:class:`.TrashBin` object. + Returns a ``TrashBin`` object. """ if self._api_version >= APIVersion(2, 16): if self._core.robot_type == "OT-3 Standard":