docs(api): Refactor liquid control section #13396

jwwojak · 2023-08-28T13:19:37Z

Overview

This PR is for managing changes made to the "Liquid Control" section of the doc, Building Block Commands.

Following the plan laid out in this Figma file. This PR is for the second small branch section in Merge Strategy 1 of the Figma file.

The original manipulating tips section has 6 parts:

Aspirate
Dispense
Blow out
Touch tip
Mix
Air gap

Test Plan

Check code in the Black formatter and use that style.
Make sure links work.
The usual grammar, style, clarity stuff.

Changelog

Adding text about the protocol template the code samples work with.
Change headers to match current style.
Revise text and code examples in each section.

Review requests

The usual suspects.

Risk assessment

Low, docs changes only.

Added a comment to make this different from the branch, docs-refactor-building-blocks-commands to create a draft PR.

codecov · 2023-08-28T13:25:04Z

Codecov Report

❗ No coverage uploaded for pull request base (docs-refactor-building-block-commands@7cb545f). Click here to learn what that means.
The diff coverage is n/a.

❗ Current head 67d6039 differs from pull request most recent head 6a290da. Consider uploading reports for the commit 6a290da to get more accurate results

Additional details and impacted files

@@                           Coverage Diff                            @@
##             docs-refactor-building-block-commands   #13396   +/-   ##
========================================================================
  Coverage                                         ?   71.68%           
========================================================================
  Files                                            ?     2427           
  Lines                                            ?    67568           
  Branches                                         ?     7779           
========================================================================
  Hits                                             ?    48433           
  Misses                                           ?    17306           
  Partials                                         ?     1829

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

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

📢 Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Opentrons).

Need to make simple change to switch to a different branch.

Plus a few others throughout before lunch.

Moving on to next sections.

ecormany

Lots of little stuff but in general this section covers what it needs to!

ecormany · 2023-08-30T15:46:52Z

api/docs/v2/new_atomic_commands.rst

-****************
+==============
+
+After attaching a tip, your robot is ready to aspirate, dispense, and perform other liquid handling tasks. The API provides the following methods that help you manipulate liquids in your protocols. These include:


Some thoughts on this list…

Either the following methods or These include depending on whether this list is exhaustive — it at least appears to be w.r.t. what this page covers.

For the list itself, we probably shouldn't repeat InstrumentContext. every time, for readability.

I'm torn on whether each item should link directly to the reference, or whether it should link down this page. Each subsection begins with a :py:meth: link to the reference, for anyone who's looking for reference entries rather than prose explanations.

I was uncomfortable with the bullet list too. Let's try something different, a bit more general without links to methods or page sections. I will summarize what the page covers and let the section headers and table of contents do the work of links in a bullet list.

api/docs/v2/new_atomic_commands.rst

Utility commands next.

Co-authored-by: Ed Cormany <[email protected]>

- add shortcut to "Move To" section in robot_position - Revisions to liquid handling sections after Aspirate/Dispense - Blow out - Touch tip - Mix - Air gap Done for now, ready for another review.

In text linking to another doc, changing "well" to "pipette." Th

Minor sentence changes. Will call this done.

ecormany

This is a straightforward section, and it's definitely cleaner than before. A few more touchups and it'll be good to go!

api/docs/v2/new_atomic_commands.rst

ecormany · 2023-09-06T14:44:10Z

api/docs/v2/new_atomic_commands.rst

-.. _new-aspirate:
+ pipette.pick_up_tip()
+ pipette.aspirate(200, plate['A1'])
+ protocol.delay(seconds=5) # pause for 5 seconds


Here and everywhere, two spaces before the # that begins an inline comment. Because Black.

api/docs/v2/new_atomic_commands.rst

ecormany · 2023-09-06T14:59:49Z

api/docs/v2/new_atomic_commands.rst


+ pipette.blow_out(protocol.fixed_trash['A1']) 


This works fine on both robots for now, but we should monitor progress of RSS-290. Ticketed on our side as RTC-333.

ecormany · 2023-09-06T15:08:36Z

api/docs/v2/new_atomic_commands.rst

 radius=0.75,
 v_offset=-2)

+When ``radius=1``, the robot moves the centerline of the pipette’s plunger axis to the exact edge of the well. Sometimes this means a pipette tip may hit the well wall or edge first and bends inwards. Setting the radius to < 1 helps avoid hitting the well wall prematurely. If you need to use it, test the radius argument first before starting a protocol production run.


Maybe a chance for some levity here, along the lines of:
"The purpose of touch_tip is to touch the edges of the well, not to crash into them. Using a smaller radius and lower speed produces gentler motion. Droplets of different types of liquid behave differently, so test out these parameters in a single well before performing a full protocol run."

Ooof, that's what passes for humor? Borscht Belt here we come! Time for some Pocono Palaver. Tip your waitstaff, enjoy the veal, I'm here all week. badum tsssss.

I'd like to keep some of Seth's explanation in here. How about trying to combine some of these:

Revised
The touch_tip feature allows the pipette to touch the edges of a well gently instead of crashing into them. When radius=1 the robot moves the centerline of the pipette’s plunger axis to the edge of the well. This means a pipette tip may sometimes hit the well wall too early, causing the tip to bend inwards. A smaller radius helps avoid a premature wall collision and a lower speed produces gentler motion. Different liquid droplets behave differently, so test out these parameters in a single well before performing a full protocol run.

api/docs/v2/new_atomic_commands.rst

ecormany · 2023-09-06T15:12:44Z

api/docs/v2/new_atomic_commands.rst

-.. code-block:: python
+This example aspirates 200 µL of air 5 mm above the current well::
+
+ pipette.air_gap(volume=200)


200 is a biiiiiiig air gap. Maybe use 20, like the existing example.

The section is based on, and linked to, those sample protocol files on another page. I selected 200 b/c the linked examples use a 1000 uL pipette. Drawing 20 ul of air from a 1000 ul pipette doesn't seem like a good example (or even accurately possible). That's why this uses such a large amount of air.

From the section intro:

The examples used here assume that you've loaded the pipettes and labware from the basic :ref:protocol template <protocol-template>.

ecormany · 2023-09-06T15:13:17Z

api/docs/v2/new_atomic_commands.rst

Check for lets --> let's throughout.

Lets as in 3rd person singular is ok, right? As in giving you the ability, capability, or permission to do whatever it is. This method "allows you to do the thing"

This method lets you . . .
not

This method let's you . . .

Yeah, not one for find and replace! Regular expressions can't save you here 🤪

Batch commit. Another check and more changes to come. Co-authored-by: Ed Cormany <[email protected]>

Co-authored-by: Ed Cormany <[email protected]>

ecormany

New changes look good, this is ready to merge into the feature branch.

…-control

* Adding comments to make different from edge At top of the doc, these comments should be deleted when we're done. Had to add something to make the branch code different from edge. Can't easily open a PR if the branch and edge are the same. Simple comments easier than forcing an empty commit. * Revised summary and new intro sections Revised the intro paragraph that summarizes the page contents. Also, added the intro sections on how the page code is structured, what labware/instruments are used, and include base protocol code for Flex and OT-2 in tabs. * Remove repeated content labware and protocol This was the content used in the Examples section. Removing it because it's long and repetitious. Instead, each section will include a short sentence linking to the protocol file template/example. * docs(api): refactor-tip-handling (#13383) * New pickup tip text and code samples Includes a revised section header and intro. Focus is on pick_up_tip method. * tips revisions: iterate, drop, return, and used 3 sections. The original "iterate through tips" becomes a section on loops and tip pickup. Then, the doc picks up from the original with drop tips, return tips. Final section cleans up info about using "used" tips. More after lunch revisions to come. * Minor text adjustment * Used tips text, small edits * Tips section finish up and a first review Will run through again on Monday. Checked code snippets with base code sample/protocol. They work. Formatting via Black formatter style. * Minor text and space adjustments * Monday morning review and minor adjustments * Tips intro, simplify last sentence * Adding protocol template text and link * Apply suggestions from code review Returning to the tip handling section. Committing previous review comments. Co-authored-by: Ed Cormany <[email protected]> * Saving stashed changes after batch commit to keep text synched up * Fixed conflicts, restored H2 section header * Basic tip pick up and using a loop for pickup * Automating tip pickup intro Something weird going on. Trying again. * Working with used tips * Small changes in tip manipulation section. * API raise error, not throw an error --------- Co-authored-by: Ed Cormany <[email protected]> * docs(api): Refactor liquid control section (#13396) * New branch for Liquid Control section Added a comment to make this different from the branch, docs-refactor-building-blocks-commands to create a draft PR. * Adjust section header, make H2 Need to make simple change to switch to a different branch. * Touch tip, blow out, dispense revisions Plus a few others throughout before lunch. * Touch tip revisions * Revisions to Mix section * Air gap section revisions * Add text and link to protocol template code * End of day review edits * Remove horizontal line between sections * Aspirate section revisions * Finish aspirate revisions, start dispense * Start dispense, end of day push * Final review of aspirate, start dispense * Dispense and aspirate revisions done for now Moving on to next sections. * Blow out revisions * Starting touch tip revisions, add option sections * touch_tip and blow_out text, short small changes * Mix revisions * Mix revisions * Air gap revisions, finish Liquid Handling section Utility commands next. * Remove intro bullet list, fix Aspirate headers * Apply suggestions from code review Co-authored-by: Ed Cormany <[email protected]> * API versions capitalization and case * Mix and air_gap changes, make similar, use text * add shortcut, revise remaining liquid sections - add shortcut to "Move To" section in robot_position - Revisions to liquid handling sections after Aspirate/Dispense - Blow out - Touch tip - Mix - Air gap Done for now, ready for another review. * Suggested word change-that's it for Friday In text linking to another doc, changing "well" to "pipette." Th * Small edits to air gap and touch tip Minor sentence changes. Will call this done. * Apply suggestions from code review Batch commit. Another check and more changes to come. Co-authored-by: Ed Cormany <[email protected]> * Update api/docs/v2/new_atomic_commands.rst Co-authored-by: Ed Cormany <[email protected]> * Let's get rid of some lets * Touch tip update * Let's look for more lets --------- Co-authored-by: Ed Cormany <[email protected]> * docs(api): Refactor utility commands section (#13406) * Creating stub PR for Utility section For Building Block Commands doc. * Fix section headers * Start section summary * Section intro starting draft save * Section intro - add full method links * Section comments removed. * Delay method revisions * Utility commands intro, delay/resume, pause meths * Homing, lights, and comments * Door safety switch section * Homing and safety switch adjustments * Utility last check * Utility intro changes * Delay/resume, pause, rail light checks * Intro and comment features * Minor edits to comment and homing * Making reviewer changes * Utility delete image, fix homing * restore header lost in merge conflict * Fix merge conflicts with main PR * 1st push reorganized sections same content * Revise parent page "og" short description * Content summaries for page links * Small edit to summary intro * Apply suggestions from code review Co-authored-by: Ed Cormany <[email protected]> * Final updates --------- Co-authored-by: Ed Cormany <[email protected]>

New branch for Liquid Control section

5e7556d

Added a comment to make this different from the branch, docs-refactor-building-blocks-commands to create a draft PR.

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

jwwojak self-assigned this Aug 28, 2023

jwwojak added 7 commits August 28, 2023 09:41

Adjust section header, make H2

2ead41e

Need to make simple change to switch to a different branch.

Touch tip, blow out, dispense revisions

39cec82

Plus a few others throughout before lunch.

Touch tip revisions

bbd493f

Revisions to Mix section

263d6ca

Air gap section revisions

409c1a2

Add text and link to protocol template code

b090d36

End of day review edits

2356626

jwwojak requested a review from ecormany August 28, 2023 19:59

jwwojak and others added 8 commits August 28, 2023 16:19

Remove horizontal line between sections

0a9c39a

Aspirate section revisions

069ffe8

Finish aspirate revisions, start dispense

8e09939

Start dispense, end of day push

540f49c

Final review of aspirate, start dispense

78f701c

Dispense and aspirate revisions done for now

119f724

Moving on to next sections.

Blow out revisions

6fe65e5

Starting touch tip revisions, add option sections

c9cd266

ecormany requested changes Aug 30, 2023

View reviewed changes

jwwojak and others added 8 commits August 30, 2023 15:39

touch_tip and blow_out text, short small changes

38f3cdd

Mix revisions

84dcce4

Mix revisions

e853742

Air gap revisions, finish Liquid Handling section

47246d2

Utility commands next.

Remove intro bullet list, fix Aspirate headers

3bab789

Apply suggestions from code review

609fb7c

Co-authored-by: Ed Cormany <[email protected]>

API versions capitalization and case

4cd4eac

Mix and air_gap changes, make similar, use text

d7dd5e9

jwwojak added 3 commits September 1, 2023 14:44

add shortcut, revise remaining liquid sections

1f5aad8

- add shortcut to "Move To" section in robot_position - Revisions to liquid handling sections after Aspirate/Dispense - Blow out - Touch tip - Mix - Air gap Done for now, ready for another review.

Suggested word change-that's it for Friday

bedbc0b

In text linking to another doc, changing "well" to "pipette." Th

Small edits to air gap and touch tip

15b9f8f

Minor sentence changes. Will call this done.

jwwojak requested a review from ecormany September 5, 2023 18:09

ecormany reviewed Sep 6, 2023

View reviewed changes

jwwojak and others added 5 commits September 6, 2023 13:40

Apply suggestions from code review

66ba5ef

Batch commit. Another check and more changes to come. Co-authored-by: Ed Cormany <[email protected]>

Update api/docs/v2/new_atomic_commands.rst

d1e710b

Co-authored-by: Ed Cormany <[email protected]>

Let's get rid of some lets

4300016

Touch tip update

817d3e4

Let's look for more lets

67d6039

ecormany approved these changes Sep 7, 2023

View reviewed changes

jwwojak marked this pull request as ready for review September 7, 2023 19:59

jwwojak requested a review from a team as a code owner September 7, 2023 19:59

Merge branch 'docs-refactor-building-block-commands' into docs-liquid…

6a290da

…-control

jwwojak merged commit f48e112 into docs-refactor-building-block-commands Sep 7, 2023
11 of 16 checks passed

jwwojak deleted the docs-liquid-control branch September 18, 2023 14:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(api): Refactor liquid control section #13396

docs(api): Refactor liquid control section #13396

jwwojak commented Aug 28, 2023 •

edited

Loading

codecov bot commented Aug 28, 2023 •

edited

Loading

ecormany left a comment

ecormany Aug 30, 2023

jwwojak Aug 31, 2023

ecormany left a comment

ecormany Sep 6, 2023

ecormany Sep 6, 2023

ecormany Sep 6, 2023

jwwojak Sep 6, 2023 •

edited

Loading

ecormany Sep 6, 2023

jwwojak Sep 6, 2023

ecormany Sep 6, 2023

jwwojak Sep 6, 2023 •

edited

Loading

ecormany Sep 6, 2023

ecormany left a comment

docs(api): Refactor liquid control section #13396

docs(api): Refactor liquid control section #13396

Conversation

jwwojak commented Aug 28, 2023 • edited Loading

Overview

Test Plan

Changelog

Review requests

Risk assessment

codecov bot commented Aug 28, 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

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

jwwojak Sep 6, 2023 • edited Loading

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

jwwojak Sep 6, 2023 • edited Loading

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 28, 2023 •

edited

Loading

codecov bot commented Aug 28, 2023 •

edited

Loading

jwwojak Sep 6, 2023 •

edited

Loading

jwwojak Sep 6, 2023 •

edited

Loading