Docstrings for 1.36.0 (streamlit#8831)

README.md

@@ -26,7 +26,7 @@ $ pip install streamlit
 $ streamlit hello
 ```
 
-If this opens our sweet _Streamlit Hello_ app in your browser, you're all set! If not, head over to [our docs](https://docs.streamlit.io/library/get-started) for specific installs.
+If this opens our sweet _Streamlit Hello_ app in your browser, you're all set! If not, head over to [our docs](https://docs.streamlit.io/get-started) for specific installs.
 
 The app features a bunch of examples of what you can do with Streamlit. Jump to the [quickstart](#quickstart) section to understand how that all works.
 
@@ -52,32 +52,32 @@ $ streamlit run streamlit_app.py
 
 ### Give me more!
 
-Streamlit comes in with [a ton of additional powerful elements](https://docs.streamlit.io/library/api-reference) to spice up your data apps and delight your viewers. Some examples:
+Streamlit comes in with [a ton of additional powerful elements](https://docs.streamlit.io/develop/api-reference) to spice up your data apps and delight your viewers. Some examples:
 
 <table border="0">
   <tr>
     <td>
-      <a target="_blank" href="https://docs.streamlit.io/library/api-reference/widgets">
+      <a target="_blank" href="https://docs.streamlit.io/develop/api-reference/widgets">
         <img src="https://user-images.githubusercontent.com/7164864/217936099-12c16f8c-7fe4-44b1-889a-1ac9ee6a1b44.png" style="max-height:150px; width:auto; display:block;">
       </a>
     </td>
     <td>
-      <a target="_blank" href="https://docs.streamlit.io/library/api-reference/data/st.dataframe">
+      <a target="_blank" href="https://docs.streamlit.io/develop/api-reference/data/st.dataframe">
         <img src="https://user-images.githubusercontent.com/7164864/215110064-5eb4e294-8f30-4933-9563-0275230e52b5.gif" style="max-height:150px; width:auto; display:block;">
       </a>
     </td>
     <td>
-      <a target="_blank" href="https://docs.streamlit.io/library/api-reference/charts">
+      <a target="_blank" href="https://docs.streamlit.io/develop/api-reference/charts">
         <img src="https://user-images.githubusercontent.com/7164864/215174472-bca8a0d7-cf4b-4268-9c3b-8c03dad50bcd.gif" style="max-height:150px; width:auto; display:block;">
       </a>
     </td>
     <td>
-      <a target="_blank" href="https://docs.streamlit.io/library/api-reference/layout">
+      <a target="_blank" href="https://docs.streamlit.io/develop/api-reference/layout">
         <img src="https://user-images.githubusercontent.com/7164864/217936149-a35c35be-0d96-4c63-8c6a-1c4b52aa8f60.png" style="max-height:150px; width:auto; display:block;">
       </a>
     </td>
     <td>
-      <a target="_blank" href="https://docs.streamlit.io/library/get-started/multipage-apps">
+      <a target="_blank" href="https://docs.streamlit.io/develop/concepts/multipage-apps">
         <img src="https://user-images.githubusercontent.com/7164864/215173883-eae0de69-7c1d-4d78-97d0-3bc1ab865e5b.gif" style="max-height:150px; width:auto; display:block;">
       </a>
     </td>

component-lib/README.md

@@ -1,5 +1,5 @@
 # Streamlit Component Library
 
-An npm package that provides support code for creating [Streamlit Components](https://docs.streamlit.io/library/components).
+An npm package that provides support code for creating [Streamlit Components](https://docs.streamlit.io/develop/concepts/custom-components).
 
 The fastest way to start writing a Streamlit Component is to use our [Component Template repo](https://github.com/streamlit/component-template), which contains templates and example code.

e2e_playwright/st_exception.py

@@ -48,7 +48,7 @@ def my_func(...):
 
 ```
 
-Please see the `hash_funcs` [documentation](https://docs.streamlit.io/library/advanced-features/caching#the-hash_funcs-parameter)
+Please see the `hash_funcs` [documentation](https://docs.streamlit.io/develop/concepts/architecture/caching#the-hash_funcs-parameter)
 for more details.
             """.strip("\n")
 )

frontend/app/src/components/StreamlitDialog/DeployErrorDialogs/__snapshots__/NoRepositoryDetected.test.tsx.snap

@@ -6,7 +6,7 @@ Object {
     The app’s code is not connected to a remote GitHub repository. To deploy on Streamlit Community Cloud, please put your code in a GitHub repository and publish the current branch. Read more in
      
     <a
-      href="https://docs.streamlit.io/streamlit-community-cloud/get-started"
+      href="https://docs.streamlit.io/deploy/streamlit-community-cloud/get-started"
       rel="noopener noreferrer"
       target="_blank"
     >

frontend/app/src/urls.ts

@@ -22,13 +22,13 @@ export const COMMUNITY_URL = "https://discuss.streamlit.io"
 
 /** The URL customers are directed to for troubleshooting components. */
 export const COMPONENT_DEVELOPER_URL =
-  "https://docs.streamlit.io/library/components"
+  "https://docs.streamlit.io/develop/concepts/custom-components"
 
 /** The URL customers are directed to for troubleshooting camera permissions. */
 export const CAMERA_PERMISSION_URL =
   "https://docs.streamlit.io/knowledge-base/using-streamlit/enable-camera"
 
 export const STREAMLIT_COMMUNITY_CLOUD_DOCS_URL =
-  "https://docs.streamlit.io/streamlit-community-cloud/get-started"
+  "https://docs.streamlit.io/deploy/streamlit-community-cloud/get-started"
 export const STREAMLIT_DEPLOY_TUTORIAL_URL =
-  "https://docs.streamlit.io/knowledge-base/tutorials/deploy"
+  "https://docs.streamlit.io/deploy/tutorials"

frontend/lib/src/components/elements/DeckGlJsonChart/withMapboxToken/MapboxTokenError.tsx

@@ -59,7 +59,7 @@ const MapboxTokenError = ({
 
             <p>
               See{" "}
-              <a href="https://docs.streamlit.io/library/advanced-features/configuration#view-all-configuration-options">
+              <a href="https://docs.streamlit.io/develop/api-reference/configuration/config.toml">
                 our documentation
               </a>{" "}
               for more info on how to set config options.

frontend/lib/src/components/elements/Toast/Toast.tsx

@@ -197,7 +197,7 @@ export function Toast({ theme, body, icon, width }: ToastProps): ReactElement {
     <AlertElement
       kind={Kind.ERROR}
       body="Streamlit API Error: `st.toast` cannot be called directly on the sidebar with `st.sidebar.toast`.
-        See our `st.toast` API [docs](https://docs.streamlit.io/library/api-reference/status/st.toast) for more information."
+        See our `st.toast` API [docs](https://docs.streamlit.io/develop/api-reference/status/st.toast) for more information."
       width={width}
     />
   )

frontend/lib/src/components/widgets/Form/Form.tsx

@@ -38,7 +38,7 @@ export const MISSING_SUBMIT_BUTTON_WARNING =
   "never be sent to your Streamlit app." +
   "\n\nTo create a submit button, use the `st.form_submit_button()` function." +
   "\n\nFor more information, refer to the " +
-  "[documentation for forms](https://docs.streamlit.io/library/api-reference/control-flow/st.form)."
+  "[documentation for forms](https://docs.streamlit.io/develop/api-reference/execution-flow/st.form)."
 
 export function Form(props: Props): ReactElement {
   const {

frontend/lib/src/urls.ts

@@ -22,13 +22,13 @@ export const COMMUNITY_URL = "https://discuss.streamlit.io"
 
 /** The URL customers are directed to for troubleshooting components. */
 export const COMPONENT_DEVELOPER_URL =
-  "https://docs.streamlit.io/library/components"
+  "https://docs.streamlit.io/develop/concepts/custom-components"
 
 /** The URL customers are directed to for troubleshooting camera permissions. */
 export const CAMERA_PERMISSION_URL =
   "https://docs.streamlit.io/knowledge-base/using-streamlit/enable-camera"
 
 export const STREAMLIT_COMMUNITY_CLOUD_DOCS_URL =
-  "https://docs.streamlit.io/streamlit-community-cloud/get-started"
+  "https://docs.streamlit.io/deploy/streamlit-community-cloud/get-started"
 export const STREAMLIT_DEPLOY_TUTORIAL_URL =
-  "https://docs.streamlit.io/knowledge-base/tutorials/deploy"
+  "https://docs.streamlit.io/deploy/tutorials"

lib/setup.py

@@ -110,7 +110,7 @@ def run(self):
     project_urls={
         "Source Code": "https://github.com/streamlit/streamlit",
         "Bug Tracker": "https://github.com/streamlit/streamlit/issues",
-        "Release notes": "https://docs.streamlit.io/library/changelog",
+        "Release notes": "https://docs.streamlit.io/develop/quick-reference/changelog",
         "Documentation": "https://docs.streamlit.io/",
         "Community": "https://discuss.streamlit.io/",
         "Twitter": "https://twitter.com/streamlit",

lib/streamlit/__init__.py

@@ -244,7 +244,7 @@ def _update_logger() -> None:
 experimental_user = _UserInfoProxy()
 
 
-_EXPERIMENTAL_QUERY_PARAMS_DEPRECATE_MSG = "Refer to our [docs page](https://docs.streamlit.io/library/api-reference/utilities/st.query_params) for more information."
+_EXPERIMENTAL_QUERY_PARAMS_DEPRECATE_MSG = "Refer to our [docs page](https://docs.streamlit.io/develop/api-reference/caching-and-state/st.query_params) for more information."
 
 experimental_get_query_params = _deprecate_func_name(
     _get_query_params,

lib/streamlit/commands/navigation.py

@@ -61,37 +61,103 @@ def navigation(
     """
     Configure the available pages in a multipage app.
 
-    Call `st.navigation` in your main script with one or more pages defined by
-    `st.Page`. `st.navigation` returns the current page which can be executed
-    using `Page.run()`.
+    Call ``st.navigation`` in your entrypoint file with one or more pages
+    defined by ``st.Page``. ``st.navigation`` returns the current page, which
+    can be executed using ``.run()`` method.
 
-    When using `st.navigation`, the main script is executed on every app rerun,
-    with the current page executed in-line using `Page.run()`. The set of
-    available pages can be updated with each rerun for dynamic navigation. In
-    this mode, the `pages/` folder is ignored.
+    When using ``st.navigation``, your entrypoint file (the file passed to
+    ``streamlit run``) acts like a router or frame of common elements around
+    each of your pages. Streamlit executes the entrypoint file with every app
+    rerun. To execute the current page, you must call the ``.run()`` method on
+    the page object returned by ``st.navigation``.
 
-    By default, `st.navigation` draws the available pages in the side
-    navigation. This behavior can be changed using the `position=` keyword
-    argument.
+    The set of available pages can be updated with each rerun for dynamic
+    navigation. By default, ``st.navigation`` draws the available pages in the
+    side navigation if there is more than one page. This behavior can be
+    changed using the ``position`` keyword argument.
+
+    As soon as any session of your app executes the ``st.navigation`` command,
+    your app will ignore the ``pages/`` directory (across all sessions).
 
     Parameters
     ----------
-    pages: list[st.Page] or dict[str, list[st.Page]]
-        A list of `st.Page` objects or a dictionary where the keys are section
-        headers and the values are lists of `st.Page` objects.
+    pages: list[StreamlitPage] or dict[str, list[StreamlitPage]]
+        The available pages for the app.
+
+        To create labeled sections or page groupings within the navigation
+        menu, ``pages`` must be a dictionary. Each key is the label of a
+        section and each value is the list of ``StreamlitPage`` objects for
+        that section.
+
+        To create a navigation menu with no sections or page groupings,
+        ``pages`` must be a list of ``StreamlitPage`` objects.
+
+        Use ``st.Page`` to create ``StreamlitPage`` objects.
 
     position: "sidebar" or "hidden"
-        The position of the navigation menu. Can be "sidebar" or "hidden".
+        The position of the navigation menu. If ``position`` is ``"sidebar"``
+        (default), the navigation widget appears at the top of the sidebar. If
+        ``position`` is ``"hidden"``, the navigation widget is not displayed.
+
+        If there is only one page in ``pages``, the navigation will be hidden
+        for any value of ``position``.
 
-    Example
+    Returns
     -------
+    StreamlitPage
+        The current page selected by the user.
+
+    Examples
+    --------
+    The following examples show possible entrypoint files, which is the file
+    you pass to ``streamlit run``. Your entrypoint file manages your app's
+    navigation and serves as a router between pages.
+
+    You can declare pages from callables or file paths.
+
+    >>> import streamlit as st
+    >>> from page_functions import page1
+    >>>
+    >>> pg = st.navigation([st.Page(page1), st.Page("page2.py")])
+    >>> pg.run()
+
+    Use a dictionary to create sections within your navigation menu.
+
     >>> import streamlit as st
-    >>> from pages import page1, page2
     >>>
-    >>>	pg = st.navigation([st.Page(page1), st.Page(page2)])
+    >>> pages = {
+    ...     "Your account" : [
+    ...         st.Page("create_account.py", title="Create your account"),
+    ...         st.Page("manage_account.py", title="Manage your account")
+    ...     ],
+    ...     "Resources" : [
+    ...         st.Page("learn.py", title="Learn about us"),
+    ...         st.Page("trial.py", title="Try it out")
+    ...     ]
+    ... }
     >>>
-    >>>	st.title("My Awesome App")
+    >>> pg = st.navigation(pages)
     >>> pg.run()
+
+    Call widget functions in your entrypoint file when you want a widget to be
+    stateful across pages. Assign keys to your common widgets and access their
+    values through Session State within your pages.
+
+    >>> import streamlit as st
+    >>>
+    >>> def page1():
+    >>>     st.write(st.session_state.foo)
+    >>>
+    >>> def page2():
+    >>>     st.write(st.session_state.bar)
+    >>>
+    >>> # Widgets shared by all the pages
+    >>> st.sidebar.selectbox("Foo", ["A", "B", "C"], key="foo")
+    >>> st.sidebar.checkbox("Bar", key="bar")
+    >>>
+    >>> pg = st.navigation(st.Page(page1), st.Page(page2))
+    >>> pg.run()
+
     """
     nav_sections = {"": pages} if isinstance(pages, list) else pages
     page_list = pages_from_nav_sections(nav_sections)

lib/streamlit/components/v1/component_registry.py

@@ -52,25 +52,40 @@ def declare_component(
     path: str | None = None,
     url: str | None = None,
 ) -> CustomComponent:
-    """Create a custom component and register it if there is a ScriptRun context.
+    """Create a custom component and register it if there is a ``ScriptRunContext``.
 
-    The component is not registered when there is no ScriptRun context; this can happen when CustomComponents are executed as standalone commands, e.g. for testing.
+    The component is not registered when there is no ``ScriptRunContext``.
+    This can happen when a ``CustomComponent`` is executed as standalone
+    command (e.g. for testing).
+
+    To use this function, import it from the ``streamlit.components.v1``
+    module.
+
+    .. warning::
+        Using ``st.components.v1.declare_component`` directly (instead of
+        importing its module) is deprecated and will be disallowd in a later
+        version.
 
     Parameters
     ----------
-    name: str
-        A short, descriptive name for the component. Like, "slider".
+    name : str
+        A short, descriptive name for the component, like "slider".
+
     path: str or None
-        The path to serve the component's frontend files from. Either
-        `path` or `url` must be specified, but not both.
+        The path to serve the component's frontend files from. If ``path`` is
+        ``None`` (default), Streamlit will server the component from the
+        location in ``url``. Either ``path`` or ``url`` must be specified, but
+        not both.
+
     url: str or None
-        The URL that the component is served from. Either `path` or `url`
-        must be specified, but not both.
+        The URL that the component is served from. If ``url`` is ``None``
+        (default), Streamlit will server the component from the location in
+        ``path``. Either ``path`` or ``url`` must be specified, but not both.
 
     Returns
     -------
     CustomComponent
-        A CustomComponent that can be called like a function.
+        A ``CustomComponent`` that can be called like a function.
         Calling the component will create a new instance of the component
         in the Streamlit app.
 

lib/streamlit/elements/arrow.py

@@ -95,12 +95,19 @@ class DataframeSelectionState(TypedDict, total=False):
     key and attribute notation. Selection states cannot be programmatically
     changed or set through Session State.
 
+    .. warning::
+        If a user sorts a dataframe, row selections will be reset. If your
+        users need to sort and filter the dataframe to make selections, direct
+        them to use the search function in the dataframe toolbar instead.
+
     Attributes
     ----------
     rows : list[int]
-        The selected rows, identified by their positional index. The positional
-        indices match the original dataframe, even if the user sorts the
-        dataframe in their browser.
+        The selected rows, identified by their integer position. The integer
+        positions match the original dataframe, even if the user sorts the
+        dataframe in their browser. For a ``pandas.DataFrame``, you can
+        retrieve data from its interger position using methods like ``.iloc[]``
+        or ``.iat[]``.
     columns : list[str]
         The selected columns, identified by their names.
 
@@ -150,8 +157,12 @@ class DataframeState(TypedDict, total=False):
 
     Attributes
     ----------
-    selection : DataframeSelectionState
-        The state of the ``on_select`` event.
+    selection : dict
+        The state of the ``on_select`` event. This attribure returns a
+        dictionary-like object that supports both key and attribute notation.
+        The attributes are described by the ``DataframeSelectionState``
+        dictionary schema.
+
 
     """
 
@@ -346,7 +357,7 @@ def dataframe(
               to change the displayed name of the column to "Dollar values"
               and add a "$" prefix in each cell. For more info on the
               available column types and config options, see
-              `Column configuration <https://docs.streamlit.io/library/api-reference/data/st.column_config>`_.
+              `Column configuration <https://docs.streamlit.io/develop/api-reference/data/st.column_config>`_.
 
             To configure the index column(s), use ``_index`` as the column name.
 

lib/streamlit/elements/deck_gl_json_chart.py

@@ -66,7 +66,7 @@ def pydeck_chart(
 
         To get a token for yourself, create an account at https://mapbox.com.
         For more info on how to set config options, see
-        https://docs.streamlit.io/library/advanced-features/configuration
+        https://docs.streamlit.io/develop/api-reference/configuration/config.toml.
 
         Parameters
         ----------

lib/streamlit/elements/dialog_decorator.py

@@ -127,9 +127,11 @@ def dialog_decorator(
     handling any side effects of that behavior.
 
     .. warning::
-        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.
+        Only one dialog function may be called in a script run, which means
+        that only one dialog can be open at any given time. Since a dialog is
+        also a fragment, all fragment limitations apply. Dialogs can't contain
+        fragments, and fragments can't contain dialogs. Using dialogs in widget
+        callback functions is not supported.
 
     .. |st.experimental_fragment| replace:: ``st.experimental_fragment``
     .. _st.experimental_fragment: https://docs.streamlit.io/develop/api-reference/execution-flow/st.fragment