Docstrings for 1.34.0 (#8588)

## Describe your changes
Update docstrings for new features added for version 1.34.0.
* Audio and video autoplay (and mute)
* Text background colors
* Material icons support
* ``st.dialog`` 🎉 
*  ``st.query_params.from_dict()``

## Testing Plan
None. Docstrings only and one parameter name change.

---

**Contribution License Agreement**
By submitting this pull request you agree that all contributions to this
project are made under the Apache 2.0 license.

lib/streamlit/commands/page_config.py

@@ -136,22 +136,50 @@ def set_page_config(
     page_title: str or None
         The page title, shown in the browser tab. If None, defaults to the
         filename of the script ("app.py" would show "app • Streamlit").
-    page_icon : Anything supported by st.image or str or None
-        The page favicon.
-        Besides the types supported by `st.image` (like URLs or numpy arrays),
-        you can pass in an emoji as a string ("🦈") or a shortcode (":shark:").
-        If you're feeling lucky, try "random" for a random emoji!
-        Emoji icons are courtesy of Twemoji and loaded from MaxCDN.
+
+    page_icon : Anything supported by st.image, str, or None
+        The page favicon. If ``page_icon`` is ``None`` (default), the favicon
+        will be a monochrome Streamlit logo.
+
+        In addition to the types supported by ``st.image`` (like URLs or numpy
+        arrays), the following strings are valid:
+
+        * A single-character emoji. For example, you can set ``page_icon="🦈"``.
+
+        * An emoji short code. For example, you can set ``page_icon=":shark:"``.
+          For a list of all supported codes, see
+          https://share.streamlit.io/streamlit/emoji-shortcodes.
+
+        * The string literal, ``"random"``. You can set ``page_icon="random"``
+          to set a random emoji from the supported list above. Emoji icons are
+          courtesy of Twemoji and loaded from MaxCDN.
+
+        * An icon from the Material Symbols library (outlined style) in the
+          format ``":material/icon_name:"`` where "icon_name" is the name
+          of the icon in snake case.
+
+          For example, ``icon=":material/thumb_up:"`` will display the
+          Thumb Up icon. Find additional icons in the `Material Symbols \
+          <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+          font library.
+
+        .. note::
+            Colors are not supported for Material icons. When you use a
+            Material icon for favicon, it will be black, regardless of browser
+            theme.
+
     layout: "centered" or "wide"
         How the page content should be laid out. Defaults to "centered",
         which constrains the elements into a centered column of fixed width;
         "wide" uses the entire screen.
+
     initial_sidebar_state: "auto", "expanded", or "collapsed"
         How the sidebar should start out. Defaults to "auto",
         which hides the sidebar on small devices and shows it otherwise.
         "expanded" shows the sidebar initially; "collapsed" hides it.
         In most cases, you should just use "auto", otherwise the app will
         look bad when embedded and viewed on mobile.
+
     menu_items: dict
         Configure the menu that appears on the top-right side of this app.
         The keys in this dict denote the menu item you'd like to configure:

lib/streamlit/elements/alert.py

@@ -39,11 +39,22 @@ def error(
         ----------
         body : str
             The error text to display.
-        icon : str or None
-            An optional argument that specifies an emoji to use as
-            the icon for the alert. Shortcodes are not allowed, please use a
-            single character instead. E.g. "🚨", "🔥", "🤖", etc.
-            Defaults to None, which means no icon is displayed.
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            * A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            * An icon from the Material Symbols library (outlined style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+              font library.
 
         Example
         -------
@@ -72,11 +83,22 @@ def warning(
         ----------
         body : str
             The warning text to display.
-        icon : str or None
-            An optional argument that specifies an emoji to use as
-            the icon for the alert. Shortcodes are not allowed, please use a
-            single character instead. E.g. "🚨", "🔥", "🤖", etc.
-            Defaults to None, which means no icon is displayed.
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            * A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            * An icon from the Material Symbols library (outlined style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+              font library.
 
         Example
         -------
@@ -104,11 +126,22 @@ def info(
         ----------
         body : str
             The info text to display.
-        icon : str or None
-            An optional argument that specifies an emoji to use as
-            the icon for the alert. Shortcodes are not allowed, please use a
-            single character instead. E.g. "🚨", "🔥", "🤖", etc.
-            Defaults to None, which means no icon is displayed.
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            * A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            * An icon from the Material Symbols library (outlined style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+              font library.
 
         Example
         -------
@@ -137,11 +170,22 @@ def success(
         ----------
         body : str
             The success text to display.
-        icon : str or None
-            An optional argument that specifies an emoji to use as
-            the icon for the alert. Shortcodes are not allowed, please use a
-            single character instead. E.g. "🚨", "🔥", "🤖", etc.
-            Defaults to None, which means no icon is displayed.
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            * A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            * An icon from the Material Symbols library (outlined style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+              font library.
 
         Example
         -------

lib/streamlit/elements/dialog_decorator.py

@@ -94,56 +94,81 @@ def dialog_decorator(title: F | None, *, width: DialogWidth = "small") -> F:
 def dialog_decorator(
     title: F | None | str = "", *, width: DialogWidth = "small"
 ) -> F | Callable[[F], F]:
-    r"""Decorate a function to mark it as a Streamlit dialog. When the decorated function is called, a dialog element is inserted with the function's body as the content.
+    """Function decorator to create a modal dialog.
 
-    The decorated function can hold multiple elements which are rendered inside of a modal when the decorated function is called.
-    The decorated function is using `st.experimental_fragment`, which means that interacting with elements inside of the dialog will
-    only re-run the dialog function.
+    A function decorated with ``@st.experimental_dialog`` becomes a dialog
+    function. When you call a dialog function, Streamlit inserts a modal dialog
+    into your app. Streamlit element commands called within the dialog function
+    render inside the modal dialog.
 
-    The decorated function can accept arguments that can be passed when it is called.
+    The dialog function can accept arguments that can be passed when it is
+    called. Any values from the dialog that need to be accessed from the wider
+    app should generally be stored in Session State.
 
-    Dismissing a dialog does not cause an app re-run.
-    You can close the dialog programmatically by executing `st.rerun()` explicitly inside of the decorated function.
+    A user can dismiss a modal dialog by clicking outside of it, clicking the
+    "**X**" in its upper-right corner, or pressing``ESC`` on their keyboard.
+    Dismissing a modal dialog does not trigger an app rerun. To close the modal
+    dialog programmatically, call ``st.rerun()`` explicitly inside of the
+    dialog function.
 
-    In order to pass state from dialog widgets to the app, you can leverage `st.session_state`.
+    ``st.experimental_dialog`` inherits behavior from |st.experimental_fragment|_.
+    When a user interacts with an input widget created inside a dialog function,
+    Streamlit only reruns the dialog function instead of the full script.
+
+    Calling ``st.sidebar`` in a dialog function is not supported.
+
+    Dialog code can interact with Session State, imported modules, and other
+    Streamlit elements created outside the dialog. Note that these interactions
+    are additive across multiple dialog reruns. You are responsible for
+    handling any side effects of that behavior.
 
     .. warning::
-        Currently, a dialog may not open another dialog.
-        Also, only one dialog-decorated function may be called in a script run, which means that only one dialog can be open at any given time.
+        A dialog may not open another dialog. Only one dialog function may be
+        called in a script run, which means that only one dialog can be open at
+        any given time.
+
+    .. |st.experimental_fragment| replace:: ``st.experimental_fragment``
+    .. _st.experimental_fragment: https://docs.streamlit.io/develop/api-reference/execution-flow/st.fragment
 
     Parameters
     ----------
     title : str
-        A string that will be used as the dialog's title. It cannot be empty.
+        The title to display at the top of the modal dialog. It cannot be empty.
     width : "small", "large"
-        The width of the dialog. Defaults to "small".
-
-    Returns
-    -------
-    A decorated function that, when called, inserts a dialog element context container. The container itself contains the decorated function's elements.
+        The width of the modal dialog. If ``width`` is ``"small`` (default), the
+        modal dialog will be 500 pixels wide. If ``width`` is ``"large"``, the
+        modal dialog will be about 750 pixels wide.
 
     Examples
     --------
-    You can annotate a function to mark it as a Streamlit dialog function and pass arguments to it. You can either dismiss the dialog via the ESC-key or the X-button or close it programmatically and trigger a re-run by using `st.rerun()`.
-    Leverage `st.session_state` if you want to pass dialog widget states to the overall app:
+    The following example demonstrates the basic usage of ``@st.experimental_dialog``.
+    In this app, clicking "**A**" or "**B**" will open a modal dialog and prompt you
+    to enter a reason for your vote. In the modal dialog, click "**Submit**" to record
+    your vote into Session State and rerun the app. This will close the modal dialog
+    since the dialog function is not called during the full-script rerun.
 
     >>> import streamlit as st
     >>>
-    >>> @st.experimental_dialog("Streamlit Example Dialog")
-    >>> def example_dialog(some_arg: str, some_other_arg: int):
-    >>>     st.write(f"You passed following args: {some_arg} | {some_other_arg}")
-    >>>     # interacting with the text_input only re-runs `example_dialog`
-    >>>     some_text_input = st.text_input("Type something:", key="example_dialog_some_text_input")
-    >>>     # following write is updated when chaning the text_input inside the dialog
-    >>>     st.write(f"You wrote '{some_text_input}' in the dialog")
-    >>>     if st.button("Close the dialog"):
+    >>> @st.experimental_dialog("Cast your vote")
+    >>> def vote(item):
+    >>>     st.write(f"Why is {item} your favorite?")
+    >>>     reason = st.text_input("Because...")
+    >>>     if st.button("Submit"):
+    >>>         st.session_state.vote = {"item": item, "reason": reason}
     >>>         st.rerun()
     >>>
-    >>> if st.button("Open dialog"):
-    >>>     example_dialog("Some string arg", 42)
-    >>>
-    >>> # following write is updated with the dialog's text input when the dialog was opened, the text input was interacted with and a re-run was triggered, e.g. by clicking the Close-button defined in `example_dialog`
-    >>> st.write(f"You wrote '{st.session_state.get('example_dialog_some_text_input', '')}' in the dialog")
+    >>> if "vote" not in st.session_state:
+    >>>     st.write("Vote for your favorite")
+    >>>     if st.button("A"):
+    >>>         vote("A")
+    >>>     if st.button("B"):
+    >>>         vote("B")
+    >>> else:
+    >>>     f"You voted for {st.session_state.vote['item']} because {st.session_state.vote['reason']}"
+
+    .. output::
+        https://doc-dialog.streamlit.app/
+        height: 350px
 
     """
 

lib/streamlit/elements/empty.py

@@ -33,12 +33,12 @@ def empty(self) -> DeltaGenerator:
         several elements at once (using a child multi-element container).
 
         To insert/replace/clear an element on the returned container, you can
-        use "with" notation or just call methods directly on the returned object.
+        use ``with`` notation or just call methods directly on the returned object.
         See examples below.
 
         Examples
         --------
-        Overwriting elements in-place using "with" notation:
+        Overwriting elements in-place using ``with`` notation:
 
         >>> import streamlit as st
         >>> import time
@@ -82,7 +82,7 @@ def _skeleton(self, *, height: int | None = None) -> DeltaGenerator:
         several elements at once (using a child multi-element container).
 
         To insert/replace/clear an element on the returned container, you can
-        use "with" notation or just call methods directly on the returned object.
+        use ``with`` notation or just call methods directly on the returned object.
         See some of the examples below.
 
         This is an internal method and should not be used directly.

lib/streamlit/elements/form.py

@@ -123,7 +123,7 @@ def form(
         Submit button is pressed, all widget values inside the form will be
         sent to Streamlit in a batch.
 
-        To add elements to a form object, you can use "with" notation
+        To add elements to a form object, you can use ``with`` notation
         (preferred) or just call methods directly on the form. See
         examples below.
 
@@ -157,7 +157,7 @@ def form(
 
         Examples
         --------
-        Inserting elements using "with" notation:
+        Inserting elements using ``with`` notation:
 
         >>> import streamlit as st
         >>>

lib/streamlit/elements/heading.py

@@ -69,8 +69,10 @@ def header(
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
         anchor : str or False
             The anchor name of the header that can be accessed with #anchor
@@ -140,8 +142,10 @@ def subheader(
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
         anchor : str or False
             The anchor name of the header that can be accessed with #anchor
@@ -213,8 +217,10 @@ def title(
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
         anchor : str or False
             The anchor name of the header that can be accessed with #anchor