Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(api): new behavior for Labware.set_offset() in PAPI 2.18 #14967

Merged
merged 3 commits into from
Apr 30, 2024

Conversation

ecormany
Copy link
Contributor

@ecormany ecormany commented Apr 19, 2024

Overview

Documents updated behavior for Labware.set_offset() in Python API version 2.18.

Addresses RTC-234

Test Plan

Sandbox:

Changelog

  • adapted new docstring draft written by @sfoster1
  • adapt sample code and move it to Advanced Control

Review requests

have we accurately captured the three phases of behavior (2.12–13, 14–17, 18+)?

Risk assessment

none

@ecormany ecormany added docs papi-v2 Python API V2 labels Apr 19, 2024
@ecormany ecormany changed the title updated set_offset docstring docs(api): new behavior for Labware.set_offset() in PAPI 2.18 Apr 19, 2024
@ecormany ecormany marked this pull request as ready for review April 22, 2024 18:56
@ecormany ecormany requested a review from a team as a code owner April 22, 2024 18:56
@ecormany ecormany requested review from sfoster1 and jwwojak April 22, 2024 18:56

The effects of ``set_offset()`` vary depending on the API level of your protocol.

.. list-table::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great use of a table here.

Comment on lines 584 to 592
- In API level 2.13 and earlier, the offset applies only to the labware
instance that ``set_offset()`` is called on.
- In API levels 2.14–2.17, ``set_offset()`` is not available, and the API
raises an error.
- In API level 2.18 and newer, the offset applies to any labware of the
same type, in the same on-deck location. Labware type is defined as the
combination of the ``loadName``, ``namespace``, and ``version`` parameters
of :py:meth:`~.ProtocolContext.load_labware`.
See :ref:`labware-offset-behavior` for examples.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if a table would work here, similar to above. You might get rid of some repetition via the column headers:

Col 1 header: API Level
Col 2 header: Description

Eliminates the need to repeat "In API level x.x ...". In the first column, just write "API 2.13 and earlier"

In the first and 3rd bullets, the text uses "earlier" and "newer" respectively. It might be stronger or more clear to use "older" and "newer." Something about "earlier" sort of threw me off. I had to think for a moment, which probably explains the burning smell.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we can embed a table in a docstring, although I'll give it a try.

You're right about the "earlier/newer" mismatch. Our standard is "earlier/later", and I'll update it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually this works and looks good!
image

gonna swap things around. we don't need the table twice.

Copy link
Contributor

@jwwojak jwwojak left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice, clear. Left a few comments for your consideration.

@ecormany ecormany merged commit cdecc11 into docs_release-2.18 Apr 30, 2024
20 checks passed
ecormany added a commit that referenced this pull request May 2, 2024
# Overview

Documents [updated behavior](#14940) for `Labware.set_offset()` in
Python API version 2.18.

Addresses RTC-234

# Test Plan

Sandbox:
- [API reference
entry](http://sandbox.docs.opentrons.com/docs-set_offset-updates/v2/new_protocol_api.html#opentrons.protocol_api.Labware.set_offset)
- [new
section](http://sandbox.docs.opentrons.com/docs-set_offset-updates/v2/new_advanced_running.html#labware-offset-behavior)
of Advanced Control
 
# Changelog

- adapted new docstring draft written by @sfoster1 
- adapt sample code and move it to Advanced Control

# Review requests

have we accurately captured the three phases of behavior (2.12–13,
14–17, 18+)?

# Risk assessment

none
@ecormany ecormany deleted the docs-set_offset-updates branch October 16, 2024 20:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs papi-v2 Python API V2
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants