docs(api): refactor-building-block-commands #13376
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
Codecov Report
Additional details and impacted files@@ Coverage Diff @@
## edge #13376 +/- ##
==========================================
Coverage 71.28% 71.29%
==========================================
Files 1588 2426 +838
Lines 52863 68247 +15384
Branches 3481 7978 +4497
==========================================
+ Hits 37684 48656 +10972
- Misses 14628 17721 +3093
- Partials 551 1870 +1319
Flags with carried forward coverage won't be shown. Click here to find out more. |
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.
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.
* 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]>
* 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]>
* 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
|
Changing this from draft to normal PR. However, the current doc is very long. As a result, we're going to break up the sections into separate pages. This means more changes coming, but only to the structure not the content. |
ecormany
reviewed
Sep 21, 2023
api/docs/v2/new_atomic_commands.rst
Outdated
|
|
||
| The examples in this section would be added to the following: | ||
| Building block commands execute some of the most basic actions that your robot can complete. But basic doesn’t mean these commands lack capabilities. They perform important tasks in your protocols. They're also foundational to the :ref:`complex commands <v2-complex-commands>` that help you write and run longer, more intricate procedures. |
There was a problem hiding this comment.
I think that using building block commands leads to "longer, more intricate" code. Complex commands are shortcuts — with some limitations! Maybe that help you combine multiple actions into fewer lines of code.
There was a problem hiding this comment.
Change implemented!
ecormany
approved these changes
Sep 25, 2023
|
|
||
| pipette.pick_up_tip() | ||
|
|
||
| This simple statement works because the variable ``tiprack_1`` in the sample protocol includes the on-deck location of the tip rack (Flex ``location="D3"``, OT-2 ``location=3``) *and* the ``pipette`` variable includes the argument ``tip_racks=[tiprack_1]``. Given this information, the robot moves to the tip rack and picks up a tip from position A1 in the rack. On subsequent calls to ``pick_up_tip()``, the robot will use the next available tip. For example:: |
There was a problem hiding this comment.
True Pythonistas might nitpick at the use of "variable" here, but I think it's clear enough. Let's wait until someone actually complains 😈
| location="C3" | ||
| ) | ||
|
|
||
| Next, revise the pipette's ``load_instrument()`` method to include the new tip rack in the ``tip_rack`` argument:: |
There was a problem hiding this comment.
The terminology here may be too far off base. We're definitely not modifying the method. We're modifying the code that calls the method.
Also, when you've already started with the basic template, this code isn't copy-paste-able. We're asking users to go back and modify the template. But we don't have to! InstrumentContext.tip_racks is a mutable property. You can just do:
pipette.tip_racks.append(tiprack_2)
| Dispense by Well or Location | ||
| ---------------------------- | ||
|
|
||
| The :py:meth:`~.InstrumentContext.dispense` method includes a ``location`` parameter that accepts either a ``Well`` or a ``Location``. |
There was a problem hiding this comment.
Link the classes or don't, whichever you decide for aspirate above.
There was a problem hiding this comment.
I see what's going on. Thought the linked reference in the "Aspirate by Well" section covered it. Will update to match.
| Touch Speed | ||
| ----------- | ||
|
|
||
| Touch speed controls how fast the pipette moves in mm/s during a touch tip step. The default movement speed is 60 mm/s, the minimum is 20 mm/s, and the maximum is 80 mm/s. Calling ``touch_tip`` without any arguments moves a tip at the default speed in the current well:: |
There was a problem hiding this comment.
Minimum of 20 here contradicts the versionchanged notice below. What we say here in the main text should be the minimum on the latest version of the API.
Co-authored-by: Ed Cormany <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview
This is the parent PR for revisions and updates to the API doc, Building Block Commands (
new-atomic-commands.rst).This is the parent PR for multiple changes. We're working this way because the original doc is very long. It's easier to manage the writing and reviews if we break the project up into a few smaller PRs. See this Figma file for the strategy at work here.
Earlier effort was #13282. This PR replaces that previous version.
Test Plan
Sandbox: http://sandbox.docs.opentrons.com/docs-refactor-building-block-commands/v2/
Changelog
TBD. Will update when ready.
Review requests
TBD. Will update when ready.
Risk assessment
Low, documentation changes only.