docs(api): describe new distribute() volume clamping behavior

[ecormany]

Overview

Brings the docs up to date with changes in #14253.

Tagged "do not merge" because this has PAPI 2.17 features. This PR should eventually be retargeted on the feature branch for the first robot stack version that supports 2.17.

Addresses RTC-383.

Test Plan

Check the sandbox.

Changelog

• Rewrote note about dispense volumes and moved it up in the section (it's not really about push_out anymore)
  • Clamped down on "clamping"
• Updated bullet on Versioning page
• Cleaned up docstring for volume argument of dispense()

Review requests

Is there anything more we'd like to say about dispense volumes vis-a-vis push out? I drafted this but I think it's not actually a good real-world example.

If you want to move the plunger a certain amount, regardless of how much has been
aspirated, you can calculate the values of ``volume`` and ``push_out`` based on the
:py:obj:`~InstrumentContext.current_volume` held in the pipette::

    pipette.pick_up_tip()
    plunger_amount=105
    pipette.aspirate(100, plate['A1'])
    pipette.dispense(
        volume=min(plunger_amount, pipette.current_volume), 
        location=plate['B1'], 
        push_out=max(pipette.current_volume-plunger_amount, 0)
    )   # dispense 100, push out 5
    pipette.aspirate(120, plate['A2'])
    pipette.dispense(
        volume=min(plunger_amount, pipette.current_volume), 
        location=plate['B2'], 
        push_out=max(pipette.current_volume-plunger_amount, 0)
    )   # dispense 105, push out 0, 15 left in tip
    pipette.drop_tip()
    
Note that when passing large ``push_out`` values, the plunger can't pass its physical
lower limit. For example, ``push_out=100`` will not have the effect of moving the
plunger the same distance as during a 100 µL dispense. For clearing large amounts
through the pipette, blow out instead.

Risk assessment

v v low, docs and docstrings only.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (c142da1) 67.79% compared to head (12d8462) 67.79%.

Additional details and impacted files

@@            Coverage Diff             @@
##             edge   #14315      +/-   ##
==========================================
- Coverage   67.79%   67.79%   -0.01%     
==========================================
  Files        2518     2518              
  Lines       72017    72017              
  Branches     9244     9244              
==========================================
- Hits        48826    48824       -2     
- Misses      20989    20990       +1     
- Partials     2202     2203       +1     

Flag	Coverage Δ
app	64.58% <ø> (-0.01%)	⬇️
components	49.41% <ø> (ø)
g-code-testing	92.43% <ø> (ø)
labware-library	41.11% <ø> (ø)
protocol-designer	37.93% <ø> (ø)
react-api-client	66.16% <ø> (ø)
step-generation	86.90% <ø> (ø)

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

Files	Coverage Δ
...i/src/opentrons/protocol_api/instrument_context.py	89.09% <ø> (ø)

... and 1 file with indirect coverage changes

[SyntaxColoring]

All looks correct to me. Thanks!