docs(api): liquid classes in 8.5

[emilyburghardt]

Overview

Liquid classes in API 2.24. Includes new articles covering liquid classes and liquid class definitions, plus changes throughout our Complex Commands section.

Test Plan and Hands on Testing

Changelog

-brought over liquid classes text from PR #17992

• reorganized the liquid classes article to ease into property descriptions
• build issues with images in the properties table; currently in the docs as a list to avoid this.
• adding custom liquid class creator section (and differentiate between customizing and creating from scratch)
• built out liquid class definition tables section
• updated API reference for tip handling options, get_liquid_class and define_liquid_class entries
• linked users to github schema for creating their own liquid class

Review requests

Risk assessment

[ecormany]

Many comments on liquid_classes.rst. We can work through these early next week and then move on to the other modified files.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 22.59%. Comparing base (011870e) to head (4c8654b).
Report is 1 commits behind head on chore_release-8.5.0.

Additional details and impacted files

@@                   Coverage Diff                   @@
##           chore_release-8.5.0   #18619      +/-   ##
=======================================================
- Coverage                24.08%   22.59%   -1.50%     
=======================================================
  Files                     3265     3258       -7     
  Lines                   282662   281767     -895     
  Branches                 29924    29872      -52     
=======================================================
- Hits                     68079    63659    -4420     
- Misses                  214558   218083    +3525     
  Partials                    25       25              

Flag	Coverage Δ
protocol-designer	18.70% <ø> (ø)
step-generation	4.32% <ø> (-1.13%)	⬇️

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

see 133 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ecormany]

Reviewed the Complex Commands pages. Biggest systematic change would be if we decided to not use the term "basic". As I read through, I realized that you use the term passim and it could be a pain to change every instance. So I would suggest focusing on rewording only the instances of "basic complex" back-to-back, which are fewer.

[ecormany]

Thanks for the persistent work to put together this huge docs PR for a huge new feature. Everything looks really solid and should give our users a solid basis for understanding liquid classes. I'm sure there will be additions and corrections in the future, but this is good to go for now!

[sanni-t]

This is really great! Thanks for the hard work @emilyburghardt (and all the reviewers too)!! The graphics look so cool @jacksonseidenberg!

The only important thing I think missing is that none of the Liquid classes articles link to the complex commands articles (unless I missed it). So even though there are links to the liquid-class based transfers' API reference, I could not find the details of how to use the new methods until I navigated to the 'Complex Commands' section on my own since I knew where to look.

I think we can add a link to the complex commands page when InstrumentContext.transfer_with_liquid_class() is introduced in the example in the Liquid Classes article &/or in the API reference for the LC transfer methods. What do you think?

[ddcc4]

Small question about this: How does this schematic indicate the submerge position? Usually we want users to pick a submerge position that's inside the liquid, right?

[emilyburghardt]

Two good callouts here.

@sanni-t I'm totally fine adding a link to the complex commands page. will probably combine this in a PR with another small change I need to make for Caila.

@ddcc4 I think what we mean here is submerge start position. If I'm right, this is just called "submerge position" in the liquid class definition, which is why I left it that way in the table.

[ddcc4]

Oh! If that's the submerge start position, then this picture makes sense. Thanks!

[ddcc4]

I must have been thinking of "aspiratePosition" and "dispensePosition" when I was looking at this picture, but I guess we don't have pictures for those?