docs(api): new_pipette.rst revisions for Flex #13218

jwwojak · 2023-08-02T17:43:58Z

Overview

Suggested text and code example revisions to the Pipette API docs (new_pipette.rst file) to include Flex text and code examples.

Sandbox link: http:https://sandbox.docs.opentrons.com/pipette-docs-revisions/v2/

Test Plan

Checked links and cross-references to make sure they work.
Asking reviewers to check doc code changes. Revisions replace sample code showing OT-2 examples in favor of Flex examples.

Changelog

Changes include:

Extensive text re-writing throughout.
Some new headers and reorganization.
Removed some references or text to OT-2 GEN1 pipettes. Emphasis is on OT-2 GEN2 and Flex pipettes.
Sample code changes from OT-2 examples to Flex.
Simplifying flow rate data. Remove duplicated info, use tables for better info display.

Review requests

Please 2x check the code samples.

Also, perhaps @SyntaxColoring could take a look at the section titled "Loading a Flex 96-Channel Pipette." The example puts the 96 channel in the left slot( mount='left'). It's a simple load_instrument example, but maybe there's more to add or a better example to give users. Any input would be appreciated.

Risk assessment

Low. Documentation changes only. Any removed OT-2 GEN1 pipette info has been saved separately in case we need to restore it.

Mid-day save

End of day commit

Midmorning save, just in case.

Culling tables and organizing pipette types. Lunch commit.

End of day save

Mid day save.

End of day save.

Early morning save up.

Moar saving.

More before lunch.

mid afternoon save

End of day revisions and save.

Top 'o the morning save.

Updated flow rates. May open draft PR.

Added comment about table alignment.

Small tweak. final final final. Open pr.

codecov · 2023-08-02T17:50:04Z

Codecov Report

Merging #13218 (5a490b9) into edge (e8c8807) will not change coverage.
Report is 14 commits behind head on edge.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             edge   #13218   +/-   ##
=======================================
  Coverage   72.32%   72.32%           
=======================================
  Files        2399     2399           
  Lines       66338    66338           
  Branches     7383     7383           
=======================================
  Hits        47978    47978           
  Misses      16594    16594           
  Partials     1766     1766

Flag	Coverage Δ
g-code-testing	`96.44% <ø> (ø)`
notify-server	`89.13% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Fix/condense flow rate tables.

Change flow rate section title. Add some comments.

Change header for GEN2 - GEN1 pipette comparisons

Table formatting fix because of comment on preceeding line.

ecormany

Whew, this page is in fact a lot! It's definitely organized better than before. I did leave several comments on improving structure further. Another pass through and this should be good.

ecormany · 2023-08-03T18:25:28Z

api/docs/v2/new_pipette.rst


-.. code-block:: python
- :substitutions:
+Similar to working with labware and modules, you must inform the robot about the pipettes you want to use in your protocol. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly.


this language, "you must inform the robot about the pipettes you want to use in your protocol", repeats the opening sentence too closely. the rest of the info in this ¶ is good.

Removing that paragraph and incorporating into 2nd paragraph of 1st section.

Similar to working with labware and modules, you must inform the robot about the pipettes you want to use in your protocol. As noted above, the:py:meth:~.ProtocolContext.load_instrument method provides this capability. It also requires the :ref:pipette's API load name <new-pipette-models>, its left or right mount position, and (optionally) a list of associated tip racks. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by load_instrument() are attached properly.

api/docs/v2/new_pipette.rst

Lunch time special. Saving. More tk.

Moved tip racks up in the TOC. Added subsections for multi-channel pipettes and well plates. Pushing from local and will now address on-line repo comments.

A decent draft push. This is ready for the regular PR process, I think. Will push and convert.

jwwojak · 2023-08-07T20:01:38Z

Turning this into a regular PR and re-requesting review.

Duplicated similar text that should have appeared in a Note. Removing the similar text.

And revising some tables and table headers.

Simplify examples. Consolidate each rate type into 1 sample block.

ecormany

Great, only a few things that didn't land in their final spot or needed a little cleanup. 🔜

ecormany · 2023-08-08T18:17:35Z

api/docs/v2/new_pipette.rst

-You load pipettes in a protocol using the :py:meth:`~.ProtocolContext.load_instrument` method. This method requires the :ref:`pipette's API load name <new-pipette-models>`, its left or right mount position, and (optionally) a list of associated tip racks.
-
-Similar to working with labware and modules, you must inform the robot about the pipettes you want to use in your protocol. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly.
+Similar to working with labware and modules, you must inform the robot about the pipettes you want to use in your protocol. As noted above, the:py:meth:`~.ProtocolContext.load_instrument` method provides this capability. It also requires the :ref:`pipette's API load name <new-pipette-models>`, its left or right mount position, and (optionally) a list of associated tip racks. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly.


Suggested change

Similar to working with labware and modules, you must inform the robot about the pipettes you want to use in your protocol. As noted above, the:py:meth:`~.ProtocolContext.load_instrument` method provides this capability. It also requires the :ref:`pipette's API load name <new-pipette-models>`, its left or right mount position, and (optionally) a list of associated tip racks. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly.

Similar to working with labware and modules, you must inform the robot about the pipettes you want to use in your protocol. As noted above, the :py:meth:`~.ProtocolContext.load_instrument` method provides this capability. It also requires the :ref:`pipette's API load name <new-pipette-models>`, its left or right mount position, and (optionally) a list of associated tip racks. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App and the robot won't let you start the protocol run until all pipettes loaded by ``load_instrument()`` are attached properly.

syntax fix

api/docs/v2/new_pipette.rst

ecormany · 2023-08-08T18:20:26Z

api/docs/v2/new_pipette.rst


 .. versionadded:: 2.0

+When you load a pipette in this way, you are declaring that you want the specified pipette to be attached to the robot. Even if you don't use the pipette anywhere else in your protocol, the Opentrons App or the touchscreen on Flex will not let your protocol proceed until all pipettes loaded with ``load_instrument`` are attached.
+
+If you're writing a protocol that uses the Flex Gripper, you might think that this would be the place in your protocol to declare that. However, the gripper doesn't require ``load_instrument``! Whether your gripper requires a protocol is determined by the presence of :py:meth:`.ProtocolContext.move_labware` commands. See :ref:`moving-labware` for more details.


should go up in the Flex section

Yikes. Yes it should. Fixing locally and will push.

ecormany · 2023-08-08T18:21:00Z

api/docs/v2/new_pipette.rst

 .. _new-multichannel-pipettes:

-Multi-Channel Pipettes
-======================
+Multi-Channel Pipettes and Well Plates


check the cross-references to make sure this won't add the text "and Well Plates" to links elsewhere.

Let's go back to the original, "Multi-Channel Pipettes." I didn't really like the extra I added on -- too long.

ecormany · 2023-08-08T18:22:13Z

api/docs/v2/new_pipette.rst


 .. code-block:: python

 def run(protocol: protocol_api.ProtocolContext):
 # Load a tiprack for 1000uL tips
 tiprack1 = protocol.load_labware(
 load_name='opentrons_flex_96_tiprack_1000ul',
- location='D1')
- # Load a wellplate
+ location='D1') 


fix indents here, Python will consider this a syntax error

2x yikes. Fixing locally. Will push revisions.

api/docs/v2/new_pipette.rst

ecormany · 2023-08-08T18:53:59Z

api/docs/v2/new_pipette.rst

+-------------------------+-------------+-----------------+-----------------+-----------------+
+| Pipette Model | Volume (µL) | Aspirate (µL/s) | Dispense (µL/s) | Blow-out (µL/s) |
+=========================+=============+=================+=================+=================+
+| Flex 1-Channel Pipette | 1-50 | 8 | 4 |


wiiiiiide boi. let's list it twice: 8, 8, 4 and 160, 160, 80

It is a wide load. We'll have to repeat the 160 and 80 three times because these have the flow rates for the 5-1000 uL pipettes:

Flex 1-channel

Flex 8-channel

Flex 96-channel

With the revision, the only metrics that get the row spans are the volumes for the pipettes. Will fix and push.

api/docs/v2/new_pipette.rst

Fix spacing

Changes from Ed's recent review. Once more unto the breech, friends!

Used wrong name for pipette position argument.

Fixing code alignment.

Revision to section intro.

api/docs/v2/new_pipette.rst

ecormany

GTG. Massive improvement and lots of new info for Flex on this page. 🦾

jwwojak · 2023-08-09T18:48:46Z

This one was a monster! Thanks, @ecormany!

jwwojak added 21 commits July 27, 2023 14:43

Starting on pipettes

6f539fb

Mid-day save

Update new_pipette.rst

567bc2a

Update new_pipette.rst

1a75d9d

End of day commit

Merge branch 'edge' into pipette-docs-revisions

59d877d

Update new_pipette.rst

5e85d5a

Midmorning save, just in case.

Update new_pipette.rst

4673e86

Culling tables and organizing pipette types. Lunch commit.

Update new_pipette.rst

593ec39

End of day save

Merge branch 'edge' into pipette-docs-revisions

b687ccb

Update new_pipette.rst

5afc092

Mid day save.

Update new_pipette.rst

e67bf8e

End of day save.

Merge branch 'edge' into pipette-docs-revisions

b376192

Morning update

566989c

Early morning save up.

Update new_pipette.rst

7bae4ff

Moar saving.

Update new_pipette.rst

5768175

More before lunch.

Update new_pipette.rst

8406a89

mid afternoon save

Update new_pipette.rst

34fe53a

End of day revisions and save.

Merge branch 'edge' into pipette-docs-revisions

5aae558

Update new_pipette.rst

5aade06

Top 'o the morning save.

Update new_pipette.rst

56a730d

Updated flow rates. May open draft PR.

Update new_pipette.rst

60e416d

Added comment about table alignment.

Update new_pipette.rst

46c4cf8

Small tweak. final final final. Open pr.

jwwojak added docs papi-v2 Python API V2 labels Aug 2, 2023

jwwojak requested a review from ecormany August 2, 2023 17:43

jwwojak self-assigned this Aug 2, 2023

jwwojak added 4 commits August 3, 2023 09:13

Update new_pipette.rst

c32820b

Fix/condense flow rate tables.

Update new_pipette.rst

5f4f237

Change flow rate section title. Add some comments.

Update new_pipette.rst

bba22fc

Change header for GEN2 - GEN1 pipette comparisons

Update new_pipette.rst

8ae27bb

Table formatting fix because of comment on preceeding line.

ecormany requested changes Aug 3, 2023

View reviewed changes

ecormany and others added 4 commits August 3, 2023 15:37

Merge branch 'edge' into pipette-docs-revisions

9e5b40d

Revisons I

5297520

Lunch time special. Saving. More tk.

Update new_pipette.rst

57c767c

Moved tip racks up in the TOC. Added subsections for multi-channel pipettes and well plates. Pushing from local and will now address on-line repo comments.

Update new_pipette.rst

4627f5e

A decent draft push. This is ready for the regular PR process, I think. Will push and convert.

jwwojak marked this pull request as ready for review August 7, 2023 20:01

jwwojak requested a review from a team as a code owner August 7, 2023 20:01

jwwojak requested a review from ecormany August 7, 2023 20:01

jwwojak added 3 commits August 7, 2023 16:35

Remove duplicated text

b08d4b3

Duplicated similar text that should have appeared in a Note. Removing the similar text.

Adding Flex flow rate data

fe71ab2

And revising some tables and table headers.

Revised flow rate code samples

f29ea94

Simplify examples. Consolidate each rate type into 1 sample block.

ecormany requested changes Aug 8, 2023

View reviewed changes

jwwojak added 5 commits August 8, 2023 14:58

Update new_pipette.rst

0bdcfa4

Fix spacing

Late day revisions

5827666

Changes from Ed's recent review. Once more unto the breech, friends!

Fixing code

a1fc577

Used wrong name for pipette position argument.

Update new_pipette.rst

4e76ddd

Fixing code alignment.

Update new_pipette.rst

e3ced30

Revision to section intro.

ecormany reviewed Aug 9, 2023

View reviewed changes

api/docs/v2/new_pipette.rst Outdated Show resolved Hide resolved

ecormany reviewed Aug 9, 2023

View reviewed changes

api/docs/v2/new_pipette.rst Outdated Show resolved Hide resolved

ecormany reviewed Aug 9, 2023

View reviewed changes

api/docs/v2/new_pipette.rst Show resolved Hide resolved

ecormany reviewed Aug 9, 2023

View reviewed changes

api/docs/v2/new_pipette.rst Outdated Show resolved Hide resolved

ecormany added 3 commits August 9, 2023 13:07

Flex flow - just merge cells

ed99981

fancier, more condensed table

f14b78f

code syntax fixes

5a88063

ecormany approved these changes Aug 9, 2023

View reviewed changes

oops, :substitutions:

5a490b9

jwwojak merged commit c3f3494 into edge Aug 9, 2023
25 checks passed

jwwojak deleted the pipette-docs-revisions branch August 10, 2023 13:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(api): new_pipette.rst revisions for Flex #13218

docs(api): new_pipette.rst revisions for Flex #13218

jwwojak commented Aug 2, 2023 •

edited

Loading

codecov bot commented Aug 2, 2023 •

edited

Loading

ecormany left a comment

ecormany Aug 3, 2023

jwwojak Aug 7, 2023

jwwojak commented Aug 7, 2023

ecormany left a comment

ecormany Aug 8, 2023

ecormany Aug 8, 2023

jwwojak Aug 8, 2023

ecormany Aug 8, 2023

jwwojak Aug 8, 2023

ecormany Aug 8, 2023

jwwojak Aug 8, 2023

ecormany Aug 8, 2023

jwwojak Aug 8, 2023

ecormany left a comment

jwwojak commented Aug 9, 2023

docs(api): new_pipette.rst revisions for Flex #13218

docs(api): new_pipette.rst revisions for Flex #13218

Conversation

jwwojak commented Aug 2, 2023 • edited Loading

Overview

Test Plan

Changelog

Review requests

Risk assessment

codecov bot commented Aug 2, 2023 • edited Loading

Codecov Report

ecormany left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jwwojak commented Aug 7, 2023

ecormany left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ecormany left a comment

Choose a reason for hiding this comment

jwwojak commented Aug 9, 2023

jwwojak commented Aug 2, 2023 •

edited

Loading

codecov bot commented Aug 2, 2023 •

edited

Loading