Docstrings for release 1.30.0 (streamlit#7916)

* Fix line break in plotly_chart docstring

* Update st.container docstring

* Remove reference to `persist` for cache_resource

* Add query_params docstrings

* Update switch_page docstring

* Revise switch_page docstring

* Docstring typos

* Add scrolling container example

lib/streamlit/commands/execution_control.py

@@ -56,7 +56,7 @@ def stop() -> NoReturn:  # type: ignore[misc]
 def rerun() -> NoReturn:  # type: ignore[misc]
     """Rerun the script immediately.
 
-    When `st.rerun()` is called, the script is halted - no more statements will
+    When ``st.rerun()`` is called, the script is halted - no more statements will
     be run, and the script will be queued to re-run from the top.
     """
 
@@ -80,7 +80,7 @@ def rerun() -> NoReturn:  # type: ignore[misc]
 def experimental_rerun() -> NoReturn:
     """Rerun the script immediately.
 
-    When `st.experimental_rerun()` is called, the script is halted - no
+    When ``st.experimental_rerun()`` is called, the script is halted - no
     more statements will be run, and the script will be queued to re-run
     from the top.
     """
@@ -94,13 +94,42 @@ def experimental_rerun() -> NoReturn:
 
 @gather_metrics("switch_page")
 def switch_page(page: str) -> NoReturn:  # type: ignore[misc]
-    """Switch the current programmatically page in a multi-page app.
-    When `st.switch_page()` is called with a page, the current page script is halted
-    and the requested page script will be queued to run from the top.
+    """Programmatically switch the current page in a multipage app.
+
+    When ``st.switch_page()`` is called, the current page execution stops and
+    the specified page runs as if the user clicked on it in the sidebar
+    navigation. The specified page must be recognized by Streamlit's multipage
+    architecture (your main Python file or a Python file in a ``pages/``
+    folder). Arbitrary Python scripts cannot be passed to ``st.switch_pages``.
+
     Parameters
     ----------
     page: str
-        The file path, relative to the main script, of the page to switch to.
+        The file path (relative to the main script) of the page to switch to.
+
+    Example
+    -------
+    Consider the following example given this file structure:
+
+    >>> your-repository/
+    >>> ├── pages/
+    >>> │   ├── page_1.py.py
+    >>> │   └── page_2.py.py
+    >>> └── your_app.py
+
+    >>> import streamlit as st
+    >>>
+    >>> if st.button("Home"):
+    >>>     st.switch_page("your_app.py")
+    >>> if st.button("Page 1"):
+    >>>     st.switch_page("pages/page_1.py")
+    >>> if st.button("Page 2"):
+    >>>     st.switch_page("pages/page_2.py")
+
+    .. output ::
+        https://doc-switch-page.streamlit.app/
+        height: 350px
+
     """
 
     ctx = get_script_run_ctx()

lib/streamlit/elements/layouts.py

@@ -93,7 +93,36 @@ def container(
 
         .. output ::
             https://doc-container2.streamlit.app/
-            height: 480px
+            height: 300px
+
+        Using ``height`` to make a grid:
+
+        >>> import streamlit as st
+        >>>
+        >>> row1 = st.columns(3)
+        >>> row2 = st.columns(3)
+        >>>
+        >>> for col in row1 + row2:
+        >>>     tile = col.container(height=120, border=True)
+        >>>     tile.title(":balloon:")
+
+        .. output ::
+            https://doc-container3.streamlit.app/
+            height: 350px
+
+        Using ``height`` to create a scrolling container for long content:
+
+        >>> import streamlit as st
+        >>>
+        >>> long_text = "Lorem ipsum. " * 1000
+        >>>
+        >>> with st.container(height=300):
+        >>>     st.markdown(long_text)
+
+        .. output ::
+            https://doc-container4.streamlit.app/
+            height: 400px
+
         """
         block_proto = BlockProto()
         block_proto.allow_empty = False

lib/streamlit/elements/plotly_chart.py

@@ -98,7 +98,7 @@ def plotly_chart(
 
         Parameters
         ----------
-        figure_or_data : plotly.graph_objs.Figure, plotly.graph_objs.Data,
+        figure_or_data : plotly.graph_objs.Figure, plotly.graph_objs.Data,\
             dict/list of plotly.graph_objs.Figure/Data
 
             See https://plot.ly/python/ for examples of graph descriptions.

lib/streamlit/runtime/caching/cache_resource_api.py

@@ -303,8 +303,6 @@ def _decorator(
               <https://docs.python.org/3/library/datetime.html#timedelta-objects>`_,
               e.g. ``timedelta(days=1)``.
 
-            Note that ``ttl`` will be ignored if ``persist="disk"`` or ``persist=True``.
-
         max_entries : int or None
             The maximum number of entries to keep in the cache, or None
             for an unbounded cache. When a new entry is added to a full cache,

lib/streamlit/runtime/state/query_params_proxy.py

@@ -20,7 +20,8 @@
 
 
 class QueryParamsProxy(MutableMapping[str, str]):
-    """A stateless singleton that proxies `st.query_params` interactions
+    """
+    A stateless singleton that proxies ``st.query_params`` interactions
     to the current script thread's QueryParams instance.
     """
 
@@ -68,15 +69,51 @@ def __setattr__(self, key: str, value: Union[str, Iterable[str]]) -> None:
 
     @gather_metrics("query_params.get_all")
     def get_all(self, key: str) -> List[str]:
+        """
+        Get a list of all query parameter values associated to a given key.
+
+        When a key is repeated as a query parameter within the URL, this method
+        allows all values to be obtained. In contrast, dict-like methods only
+        retrieve the last value when a key is repeated in the URL.
+
+        Parameters
+        ----------
+        key: str
+            The label of the query parameter in the URL.
+
+        Returns
+        -------
+        List[str]
+            A list of values associated to the given key. May return zero, one,
+            or multiple values.
+        """
         with get_session_state().query_params() as qp:
             return qp.get_all(key)
 
     @gather_metrics("query_params.clear")
     def clear(self) -> None:
+        """
+        Clear all query parameters from the URL of the app.
+
+        Returns
+        -------
+        None
+        """
         with get_session_state().query_params() as qp:
             qp.clear()
 
     @gather_metrics("query_params.to_dict")
     def to_dict(self) -> Dict[str, str]:
+        """
+        Get all query parameters as a dictionary.
+
+        When a key is repeated as a query parameter within the URL, this method
+        will return only the last value of each unique key.
+
+        Returns
+        -------
+        Dict[str,str]
+            A dictionary of the current query paramters in the app's URL.
+        """
         with get_session_state().query_params() as qp:
             return qp.to_dict()