docs(api): Fix description of run log payload

api/src/opentrons/execute.py

@@ -316,11 +316,32 @@ def execute(  # noqa: C901
                       ``"debug"``, ``"info"``, ``"warning"``, or ``"error"``.
                       Defaults to ``"warning"``.
     :param emit_runlog: A callback for printing the runlog. If specified, this
-                        will be called whenever a command adds an entry to the
-                        runlog, which can be used for display and progress
-                        estimation. If specified, the callback should take a
-                        single argument (the name doesn't matter) which will
-                        be a dictionary (see below). Default: ``None``
+        will be called whenever a command adds an entry to the
+        runlog, which can be used for display and progress
+        estimation. If specified, the callback should take a
+        single argument (the name doesn't matter) which will
+        be a dictionary:
+
+        .. code-block:: python
+
+          {
+            'name': command_name,
+            'payload': {
+              'text': string_command_text,
+               # The rest of this struct is
+               # command-dependent; see
+               # opentrons.commands.commands.
+             }
+          }
+
+        .. note::
+          In older software versions, ``payload["text"]`` was a
+          `format string <https://docs.python.org/3/library/string.html#formatstrings>`_.
+          To get human-readable text, you had to do ``payload["text"].format(**payload)``.
+          That usage is deprecated now. If ``payload["text"]`` happens to contain any
+          ``{`` or ``}`` characters, it can confuse ``.format()`` and cause it to raise a
+          ``KeyError``.
+
     :param custom_labware_paths: A list of directories to search for custom labware.
                                  Loads valid labware from these paths and makes them available
                                  to the protocol context. If this is ``None`` (the default), and
@@ -333,22 +354,6 @@ def execute(  # noqa: C901
                               non-recursive contents of specified directories
                               are presented by the protocol context in
                               ``ProtocolContext.bundled_data``.
-
-    The format of the runlog entries is as follows:
-
-    .. code-block:: python
-
-        {
-            'name': command_name,
-            'payload': {
-                 'text': string_command_text,
-                  # The rest of this struct is command-dependent; see
-                  # opentrons.commands.commands. Its keys match format
-                  # keys in 'text', so that
-                  # entry['payload']['text'].format(**entry['payload'])
-                  # will produce a string with information filled in
-             }
-        }
     """
     stack_logger = logging.getLogger("opentrons")
     stack_logger.propagate = propagate_logs

api/src/opentrons/simulate.py

@@ -440,14 +440,22 @@ def simulate(
     Each dict element in the run log has the following keys:
 
         - ``level``: The depth at which this command is nested - if this an
-                     aspirate inside a mix inside a transfer, for instance,
-                     it would be 3.
-        - ``payload``: The command, its arguments, and how to format its text.
-                       For more specific details see
-                       ``opentrons.commands``. To format a message from
-                       a payload do ``payload['text'].format(**payload)``.
+          aspirate inside a mix inside a transfer, for instance, it would be 3.
+
+        - ``payload``: The command. The human-readable run log text is available at
+          ``payload["text"]``. The other keys of ``payload`` are command-dependent;
+          see ``opentrons.commands``.
+
+          .. note::
+            In older software versions, ``payload["text"]`` was a
+            `format string <https://docs.python.org/3/library/string.html#formatstrings>`_.
+            To get human-readable text, you had to do ``payload["text"].format(**payload)``.
+            That usage is deprecated now. If ``payload["text"]`` happens to contain any
+            ``{`` or ``}`` characters, it can confuse ``.format()`` and cause it to raise a
+            ``KeyError``.
+
         - ``logs``: Any log messages that occurred during execution of this
-                    command, as a logging.LogRecord
+          command, as a :py:obj:`logging.LogRecord`.
 
     :param protocol_file: The protocol file to simulate.
     :param file_name: The name of the file