docs(api): Fix description of run log payload

[SyntaxColoring]

Overview

While working on #13709, I noticed some outdated documentation for opentrons.simulate.simulate() and opentrons.execute.execute().

The docs say you're supposed to do this:

command = ...  # get from opentrons.simulate.simulate() or opentrons.execute.execute()

run_log_text = command["payload"]["text"].format(command["payload"])

However, it's apparently been simplified to this now:

command = ... # get from opentrons.simulate.simulate() or opentrons.execute.execute()

run_log_text = command["payload"]["text"]

I'm not sure how long this has been the case. PR #9799 suggests it's at least since v5.0.2 but doesn't provide further details ("text field is not a format string anymore"). I tried some Git archeology, but I couldn't get to the bottom of it quickly.

Unfortunately, if you try to do the old .format() thing today, it's actively harmful. If the string happens to contain any { or } characters, it will confuse .format() and raise a KeyError. This happens for Thermocycler commands (see issue #9988), and of course it can happen for ProtocolContext.comment() commands.

Test Plan

• Preview changes on http://sandbox.docs.opentrons.com/fix_payload_docs/v2/.
  • http://sandbox.docs.opentrons.com/fix_payload_docs/v2/new_protocol_api.html#opentrons.simulate.simulate
  • http://sandbox.docs.opentrons.com/fix_payload_docs/v2/new_protocol_api.html#opentrons.execute.execute

Changelog

• Document that you should just do command["payload"]["text"].
• Document that you should no longer do command["payload"]["text"].format(command["payload"]).

Review requests

• Do you see any other places where we encourage the .format() thing? Anything in the Support help center? Any demo files floating around?
• Does my flowery prose inspire joy in the depths of your heart?

Risk assessment

Low.

[codecov]

Codecov Report

Merging #13776 (8e96a4b) into edge (c8d3454) will decrease coverage by 0.11%.
Report is 24 commits behind head on edge.
The diff coverage is n/a.

Additional details and impacted files

@@            Coverage Diff             @@
##             edge   #13776      +/-   ##
==========================================
- Coverage   70.66%   70.56%   -0.11%     
==========================================
  Files        2477     2485       +8     
  Lines       69666    69779     +113     
  Branches     8453     8480      +27     
==========================================
+ Hits        49232    49239       +7     
- Misses      18448    18554     +106     
  Partials     1986     1986              

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

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

Files	Coverage Δ
api/src/opentrons/execute.py	54.23% <ø> (ø)
...i/src/opentrons/protocol_api/instrument_context.py	87.73% <ø> (ø)
api/src/opentrons/simulate.py	57.73% <ø> (ø)

... and 29 files with indirect coverage changes

[ecormany]

This looks good to me. The most important part is the inclusion of the new notes to ward people away from writing code that might break. All the little comments are possible improvements, but completely optional.

I would like to rewrite the prose earlier in each of these docstrings, but I think that's already covered in RTC-211.

[jwwojak]

Added a comment about the use of "deprecated". Does the text need a stronger warning?

[SyntaxColoring]

Failing tests appear to all be flaky Thermocycler integration tests.