Document input suggestions in the docstrings

Author: cpsievert

shiny/ui/_chat.py

@@ -133,11 +133,12 @@ async def handle_user_input(user_input: str):
         A unique identifier for the chat session. In Shiny Core, make sure this id
         matches a corresponding :func:`~shiny.ui.chat_ui` call in the UI.
     messages
-        A sequence of messages to display in the chat. Each message can be a
-        dictionary with a `content` and `role` key. The `content` key should contain
-        the message text, and the `role` key can be "assistant", "user", or "system".
-        Note that system messages are not actually displayed in the chat, but will
-        still be stored in the chat's `.messages()`.
+        A sequence of messages to display in the chat. Each message can be either a
+        string or a dictionary with `content` and `role` keys. The `content` key
+        should contain a string, and the `role` key can be "assistant" or "user".
+        Content strings are interpreted as markdown and rendered to HTML on the client.
+        Content may also include specially formatted **input suggestion** links (see
+        `.append_message_stream()` for more information).
     on_error
         How to handle errors that occur in response to user input. When `"unhandled"`,
         the app will stop running when an error occurs. Otherwise, a notification
@@ -498,11 +499,37 @@ async def append_message(self, message: Any) -> None:
             The message to append. A variety of message formats are supported including
             a string, a dictionary with `content` and `role` keys, or a relevant chat
             completion object from platforms like OpenAI, Anthropic, Ollama, and others.
+            Content strings are interpreted as markdown and rendered to HTML on the
+            client. Content may also include specially formatted **input suggestion**
+            links (see note below).
 
         Note
         ----
+        ``{.callout-note title="Input suggestions"}
+        Input suggestions are special links that send text to the user input box when
+        clicked (or accessed via keyboard). They can be created in the following ways:
+
+        * `<span class='suggestion'>Suggestion text</span>`: An inline text link that
+            places 'Suggestion text' in the user input box when clicked.
+        * `<img data-suggestion='Suggestion text' src='image.jpg'>`: An image link with
+            the same functionality as above.
+        * `<span data-suggestion='Suggestion text'>Actual text</span>`: An inline text
+            link that places 'Suggestion text' in the user input box when clicked.
+
+        A suggestion can also be submitted automatically by doing one of the following:
+
+        * Adding a `submit` CSS class or a `data-suggestion-submit="true"` attribute to
+          the suggestion element.
+        * Holding the `Ctrl/Cmd` key while clicking the suggestion link.
+
+        Note that a user may also opt-out of submitting a suggestion by holding the
+        `Alt/Option` key while clicking the suggestion link.
+        ```
+
+        ```{.callout-note title="Streamed messages"}
         Use `.append_message_stream()` instead of this method when `stream=True` (or
         similar) is specified in model's completion method.
+        ```
         """
         await self._append_message(message)
 
@@ -546,15 +573,40 @@ async def append_message_stream(self, message: Iterable[Any] | AsyncIterable[Any
         Parameters
         ----------
         message
-            An iterable or async iterable of message chunks to append. A variety of
-            message chunk formats are supported, including a string, a dictionary with
-            `content` and `role` keys, or a relevant chat completion object from
-            platforms like OpenAI, Anthropic, Ollama, and others.
+            An (async) iterable of message chunks to append. A variety of message chunk
+            formats are supported, including a string, a dictionary with `content` and
+            `role` keys, or a relevant chat completion object from platforms like
+            OpenAI, Anthropic, Ollama, and others. Content strings are interpreted as
+            markdown and rendered to HTML on the client. Content may also include
+            specially formatted **input suggestion** links (see note below).
 
         Note
         ----
+        ```{.callout-note title="Input suggestions"}
+        Input suggestions are special links that send text to the user input box when
+        clicked (or accessed via keyboard). They can be created in the following ways:
+
+        * `<span class='suggestion'>Suggestion text</span>`: An inline text link that
+            places 'Suggestion text' in the user input box when clicked.
+        * `<img data-suggestion='Suggestion text' src='image.jpg'>`: An image link with
+            the same functionality as above.
+        * `<span data-suggestion='Suggestion text'>Actual text</span>`: An inline text
+            link that places 'Suggestion text' in the user input box when clicked.
+
+        A suggestion can also be submitted automatically by doing one of the following:
+
+        * Adding a `submit` CSS class or a `data-suggestion-submit="true"` attribute to
+          the suggestion element.
+        * Holding the `Ctrl/Cmd` key while clicking the suggestion link.
+
+        Note that a user may also opt-out of submitting a suggestion by holding the
+        `Alt/Option` key while clicking the suggestion link.
+        ```
+
+        ```{.callout-note title="Streamed messages"}
         Use this method (over `.append_message()`) when `stream=True` (or similar) is
         specified in model's completion method.
+        ```
         """
 
         message = _utils.wrap_async_iterable(message)
@@ -1090,9 +1142,12 @@ def chat_ui(
     id
         A unique identifier for the chat UI.
     messages
-        A sequence of messages to display in the chat. Each message can be either a string
-        or a dictionary with a `content` and `role` key. The `content` key should contain
-        the message text, and the `role` key can be "assistant" or "user".
+        A sequence of messages to display in the chat. Each message can be either a
+        string or a dictionary with `content` and `role` keys. The `content` key
+        should contain a string, and the `role` key can be "assistant" or "user".
+        Content strings are interpreted as markdown and rendered to HTML on the client.
+        Content may also include specially formatted **input suggestion** links (see
+        :method:`~shiny.ui.Chat.append_message_stream` for more information).
     placeholder
         Placeholder text for the chat input.
     width